phronomy 0.29.0 → 0.30.1

data/docs/architecture/llm-continuation-metadata.md

@@ -0,0 +1,88 @@
+# LLM continuation metadata preservation
+
+This correction follows [ADR-066](../decisions/066-llm-and-tool-operation-contracts.md).
+It does not change the LLM/Tool/Agent ownership decision, add a dependency to the
+contract, or teach Agent a provider wire format.
+
+## Problem and contract
+
+The RubyLLM backend converted SDK responses into Phronomy Response values without
+their reasoning data. A later model turn therefore lost information RubyLLM could
+otherwise replay. Saved assistant records already contained Message metadata, but
+RuntimeInput reconstructed only model_id. Explicit Message imports dropped the
+metadata too. These were separate losses along the same conversation path.
+
+C09 Message/Response metadata remains immutable canonical JSON. Backend-owned
+continuation data accompanies its assistant message through a Tool round, Journal
+serialization, recovery and explicit Phronomy-message import. Agent preserves the
+value without inspecting its backend keys. Metadata does not authorize a Tool,
+change context selection, become answer content or become arbitrary SDK options.
+Record/control metadata remains distinct from metadata inside an assistant payload.
+
+The concrete RubyLLM backend owns the ruby_llm_continuation namespace, format
+version 1, and conversion of SDK thinking text/signature and raw_reasoning. It
+reconstructs those SDK options only inside the backend. RubyLLM still owns wire
+format rendering; no SDK class or provider registry is patched for this fix.
+No thinking toggle, extra model call, fallback, retry, sampling change or Tool
+execution is introduced. Existing Tool thought_signature behavior is unchanged.
+
+Streaming's final Response retains the same continuation data. Public content
+chunks remain answer chunks; this change adds no reasoning-display event API.
+SDK token usage semantics are unchanged.
+
+## Replay compatibility
+
+The backend records the requested model ID, provider, selected protocol name and
+a SHA-256 of the API base. The endpoint itself and credentials are not stored in
+the envelope. Reuse requires an exact match of this scope and format version.
+An incompatible scope/version raises ConfigurationError before sending the next
+model request. State is neither silently discarded nor sent to a different target.
+Malformed envelopes fail explicitly. Legacy messages without the envelope remain
+usable; missing historical reasoning cannot be reconstructed.
+
+This conservative equality check is not a claim that all identical endpoints are
+semantically unchanged, or that different models can never share reasoning. It
+does not detect server runtime/template changes behind one URL, account changes,
+or model replacements behind one model ID. Cross-model/provider reasoning
+conversion is outside this correction.
+
+Handoff continues to use its existing context selection policy. If a selected
+assistant message carries this state, a same-scope target can replay it and a
+different-scope RubyLLM target rejects it. Applications requiring transfer across
+incompatible scopes must intentionally select/derive portable context using the
+existing context policy; they must not forge the scope or treat metadata as
+authority. Other backend implementations own their own metadata conventions.
+
+## Persistence and compatibility
+
+There is no DB schema change, new SDK object in storage, or changed public method
+signature. RuntimeInput restores the canonical metadata Hash and uses historical
+top-level model_id only when metadata does not already contain it. Canonical
+metadata is authoritative if both representations exist. Missing metadata means
+an empty Hash; malformed non-Hash metadata is rejected.
+
+ContextImporter preserves explicitly supplied canonical Message metadata. It does
+not inspect an externally supplied RubyLLM object's thinking field; converting
+SDK-specific external histories remains a backend-boundary concern, not a new
+Agent SDK dependency. Signed/provider-shaped values stay unmodified and subject
+to the SDK 2.0.0 representation supported by the existing dependency constraint.
+This is not general preservation of every SDK field (for example server-tool
+raw_content), nor a promise of compatibility with untested providers.
+
+## Evidence and acceptance
+
+The compatibility regressions are:
+
+- spec/phronomy/llm_adapter/continuation_metadata_spec.rb: actual SDK parsing and
+  rendered HTTP for text/signature, streaming, Responses encrypted state and
+  provider-shaped OpenRouter reasoning; scope/version rejection and legacy input.
+- spec/phronomy/agent/continuation_metadata_spec.rb: real Agent Tool loops,
+  subsequent invocation, approval across reconstructed storage/Runtime, Handoff,
+  and an independent backend with opaque metadata and no RubyLLM calls.
+- spec/phronomy/agent/ruby_llm_materializer_spec.rb: historical model_id reading.
+
+The LM Studio gpt-oss-20b reasoning omission was independently reproduced before
+this change. The prior isolated A/B diagnostic returned HTTP 200 in all four
+trials. This correction therefore does not claim to explain or fix peg-native
+HTTP 400, nor to complete Example 22. Actual model behavior and the entire
+application acceptance remain separate verification stages.

data/docs/architecture/lm-studio-output-failures.md

@@ -0,0 +1,111 @@
+# LM Studio provider output failures
+
+## Scope and ownership
+
+`Phronomy::LLMAdapter::LMStudio` is an explicitly selected concrete RubyLLM
+backend. It handles rejection of the provider's generated conversation format.
+It does not parse or repair partial model output, change prompts or sampling
+parameters, split Tool/schema requests, or replay Agent/Workflow/Tool work.
+The default `RubyLLM` backend and SDK global configuration remain unchanged.
+
+C09 owns the meaning of the public `TransportError` reason code
+`llm.provider_output_parse_failed`. A code does not itself authorize retry.
+The concrete backend owns HTTP-body decoding and its transport policy under
+ADR-011/066. Application composition selects that backend and its retry limit.
+No new Contract or Contract dependency is required.
+
+## Recognition and evidence limits
+
+Recognition requires a RubyLLM BadRequestError/ServerError with its own HTTP
+response and actual HTTP status 400 or 500. The JSON body must contain `error`
+with the exact engine code 500, type `server_error`, and message:
+
+    The model produced output that does not match the expected peg-native format
+
+The engine object may be direct, or JSON after the exact LM Studio prefix
+`Engine protocol predict stream returned an error: `, carried in an error string
+or the error object's message field. No search through arbitrary strings or
+nested exception causes is performed. A malformed/unknown envelope, missing
+response or different status/type/code/message remains an ordinary SDK failure.
+The original SDK exception remains `cause`; the original HTTP status and body
+are not rewritten. The engine's internal 500 is not treated as HTTP 500.
+
+The offline HTTP fixture envelopes are synthetic. Follow-up real LM Studio
+acceptance on 2026-10-24 captured the actual HTTP 400 error body and confirmed
+classification as `llm.provider_output_parse_failed`. The eligible request was
+resent once with identical bytes. After the retry also failed, the adapter
+returned the final TransportError at its own limit; the measurement guard did
+not trigger, and Agent/Workflow work was not replayed. A separate application
+invocation completed initially with HTTP 200. Total: two application invocations
+and three generation POSTs; this is not recovery within the failed invocation.
+
+Live error identification and bounded retry are verified. Recovery by retry,
+recovery rate, the PEG root cause and recurrence resolution remain unverified.
+The unrecognized-envelope branch was not observed live. The failing host logs
+contain parser suffixes but do not establish the complete pre-parser token
+stream. Unknown formats fail closed without retry.
+
+## Retry policy and configuration
+
+```ruby
+context = RubyLLM.context do |config|
+  config.openai_api_base = "http://127.0.0.1:1234/v1"
+  config.openai_api_key = "lm-studio"
+  config.openai_protocol = :chat_completions
+  config.request_timeout = 120
+end
+
+Phronomy.configure do |config|
+  config.llm_adapter = Phronomy::LLMAdapter::LMStudio.new(
+    context: context,
+    max_parse_retries: 1 # default 0; only 0 or 1 is accepted
+  )
+end
+```
+
+The selected backend snapshots the RubyLLM 2.0 context and disables SDK retries
+within that snapshot. **Ordinary 429/500/network retries are also disabled for
+this backend.** Applications needing the existing SDK transport policy should
+keep the default RubyLLM backend; this selection is deliberately explicit.
+The caller's context and global settings are not modified. The frozen snapshot
+prevents later scalar context changes from increasing the retry budget.
+
+Only a recognized parse failure can trigger the optional second attempt. It is
+limited to non-streaming `complete`, provider `openai`, model
+`openai/gpt-oss-20b`, no advertised Tools, no response schema, and no Tool messages
+or pending Tool calls in the supplied history. The same immutable request is
+used to construct a fresh operation-local SDK chat. Total generation POSTs are
+at most two. The one-additional-attempt limit is a conservative policy choice,
+not an empirically established optimum or a reliability guarantee.
+
+Streaming is never replayed. Delivered chunks and application callback exception
+identity are preserved. Cancellation is checked before another attempt; existing
+worker lifetime and deadline behavior remain unchanged. A final failure exposes
+the final SDK exception as cause. No successful result is synthesized from an
+error body.
+
+## Observation
+
+The existing logical `llm.call` span covers the complete adapter operation.
+There is no new trace identity or dependency from C09 to C15. Individual SDK HTTP
+requests continue to use RubyLLM's instrumentation. Every failed adapter attempt
+also emits a safe warning containing attempt number, reason code, actual HTTP
+status when known, and whether a retry was selected; no prompt, raw body or
+credential is included. Therefore a later success does not erase the first
+failure from the diagnostic record.
+
+An optional concrete-backend `on_attempt:` callable receives these safe fields
+plus `outcome`. It must support concurrent calls if an adapter is shared and is
+not a durable audit store. Logging/callback failures cannot replace the business
+result or original exception. Applications can use SDK instrumentation when they
+need request correlation or detailed HTTP evidence. Successful response events
+do not invent an HTTP status that the public response does not expose.
+
+## Verification
+
+Offline contracts use a real loopback TCP HTTP server and the actual
+RubyLLM/Faraday stack. They verify status/cause fidelity, default no retry, exactly
+two POSTs for opt-in recovery/exhaustion, unchanged request JSON, excluded
+requests, cancellation between attempts, callback identity, unknown responses,
+configuration isolation and unchanged default-backend SDK retries. They do not
+invoke a live model.

data/docs/architecture/r8-unit1.md

@@ -1,4 +1,4 @@
-# r8第1適用版：Context／ToolとExecutionの共通基盤
+# r8 unit 1: Shared Context, Tool, and Execution foundations
 
 > Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
 > adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
@@ -6,99 +6,99 @@
 > `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は残さない。
+The baseline is main `653e255a34fe4062d4beca47530e084fdd3a6ba9`, checked on 2026-09-30. The design references are the revised r8 specification and directory layout documents updated that day. This change is the first implementation unit; it does not mean that all of r8, every S1 item, or every S2/S3 acceptance condition is complete. Compatibility aliases and old APIs that only forward calls are not retained.
 
-## 実装した責務と操作
+## Implemented responsibilities and operations
 
-| 所有者 | 共通基盤が実行すること | 利用側に残すこと |
+| Owner | What the shared foundation does | What remains with the caller |
 |---|---|---|
-| `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::Assembly` | Calls the Policy once and validates the Plan; normalizes content, checks the final budget, and stores the Manifest | Agent obtains the snapshot, rechecks the watermark immediately before persistence, and updates the Agent execution record |
+| `Tool::DefinitionSet` | Normalizes Tool definitions and validates name uniqueness and consistency with persisted definitions | Agent prepares its own Tool aliases, decorators, and runtime instances |
+| `Tool::Authorization` | Evaluates facts -> requirement -> policy -> decision using immutable arguments and authorization context | Agent manages execution matching, approval state, admission results, and supervision |
+| `Tool::ToolExecutor` | Handles cooperative/offloaded execution rules and results | Pool selection in Engine is delegated to the Execution mechanism binding |
+| `LLMAdapter::Base` / `RubyLLM` | Handles synchronous generation and chat construction/configuration, message construction, and tool-call construction; the RubyLLM implementation translates SDK failures | Agent validates its persisted data and Tool definitions before passing them to the adapter |
+| `Execution` | Owns the submit entry point, fan-out/fan-in, result composition, and cancellation/deadline/waiting rules | Engine implements pools, timers, Runtime, and FSM mechanisms |
+| `Tracing::Observation` | Provides explicit observation and PII redaction without changing the actual return value | Runnable owns the invoke/stream/batch execution contract |
 
-ContextとToolはAgentの薄い型定義の置場ではなく、実際の共通手順を所有する。ただし、Contextの現在の入力にはAgent由来の識別情報や由来情報が残る。完全に汎用の新domainモデルまで設計し直したものではない。ToolのDSL基底は引き続きRubyLLM::Toolを使用する。
+Context and Tool own real shared procedures, rather than merely housing thin Agent type definitions. However, current Context inputs still contain Agent-derived identifiers and provenance. This is not a redesign into a fully generic domain model. The Tool DSL base continues to use 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参加を完成させたものではない。
+`Context::Assembly#prepare(input:, policy:, adapter_identity:)` calls the Policy outside the persistence transaction. `#store(prepared, contents:)` uses only the contents repository supplied by the caller from the same transaction; it does not start an independent transaction. Initial and follow-up Agent commits store the Manifest and the AgentExecution reference within the existing transaction. If a later write fails, the Manifest is rolled back too, and the Policy is not executed again. The existing ordering, which applies the live projection after commit, is preserved. This validates the Agent/Context part of P02; it does not complete participation in outer transactions for arbitrary domains.
 
-Executionは`_ExecutionBackend`の操作に依存する。構成処理が遅延providerを設定し、Engineの`ExecutionBinding`がsubmit/afterを実装する。settled TaskResultの生成・map/flat_map/all_settled・待機制約の確認ではEngineを読み込まない。Runtime取得は実際のsubmit/タイマー登録時に行う。単なる名義移管に留めず、機構参照をここへ集約した。
+Execution depends on the operations of `_ExecutionBackend`. Composition configures a deferred provider, and Engine's `ExecutionBinding` implements submit/after. Creating settled TaskResults, using map/flat_map/all_settled, and checking waiting constraints do not load Engine. Runtime is obtained only when work is actually submitted or a timer is registered. Mechanism references are consolidated here, rather than merely being renamed or nominally reassigned.
 
-WorkflowのFINISHと終了値は`Workflow::Completion`が所有し、WorkflowRunnerがFSM側へ変換する。FSMSession専用のEvent／FSMProtocol／TerminalDecisionはEngineに置く。Agent・MultiAgentのFSM専用接続の全面分離は残っている。
+`Workflow::Completion` owns Workflow FINISH and completion values, and WorkflowRunner translates them into the FSM representation. Event/FSMProtocol/TerminalDecision, which are specific to FSMSession, live in Engine. Full separation of Agent and MultiAgent FSM-specific bindings remains outstanding.
 
-## 公開名・配置の変更
+## Public names and layout changes
 
-| 旧配置・API | 新配置・API | 判断 |
+| Previous location/API | New location/API | Rationale |
 |---|---|---|
-| `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項目別の到達点
-
-| 項目 | この適用版 | 未完了部分 |
+| `agent/context_contract/` and APIs such as `Agent::ContextPolicy` | `context/` and APIs such as `Context::ContextPolicy` | Consolidate Policy, Plan, Manifest, and validation under the owner of the shared operations |
+| `agent/context_policies/default.rb` | `context/default_policy.rb`, `Context::DefaultPolicy` | Keep the concrete Policy in the same domain |
+| `Agent::Context::Instruction::PromptTemplate` | `Context::PromptTemplate` | Remove the old public name under Agent |
+| `Agent::Selection::{Candidate,Constraint}` | `Context::{Candidate,Constraint}` | Remove the thin Selection subdivision |
+| `Agent::LLMInputPatch` / `LLMInputBuildContext` | `Context::LLMInputPatch` / `LLMInputBuildContext` | Unify ownership of hook inputs and return values |
+| `ContextBudgetExceededError` | `Context::BudgetExceededError` | Represent a Context budget failure, not an LLM provider failure |
+| `agent/context_assembly/` | `context/assembly.rb` plus preparation, state, and input handling directly under Agent | Separate shared Context procedures, Agent snapshot/state handling, and LLM SDK handling |
+| `Agent::Context::Capability::Base` | The actual implementation, `Tool::Base` | Remove the old name and alias |
+| `agent/tool_execution/tool_definition_set.rb` | `tool/definition_set.rb` | Transfer shared definition handling; keep Agent-specific construction in Agent |
+| `execution_contract/` and `execution_services/` | `execution/` and the necessary `execution/concurrency/` | Consolidate operations, values, and shared rules; do not add thin subdivisions such as `execution_result` |
+| `WorkerSubmission` | `Execution.submit` | Remove the forwarding-only module |
+| `Runnable#trace` | `Tracing::Observation.trace` | Remove the execution foundation's dependency on observation |
+| `tool/contract`, `filter/contract`, `output_parser/contract`, `agent/lifecycle_contract` | Exception files under their owning domains | Remove exception-only directories; retain existing meaningful exception constant names as actual definitions |
+
+Custom LLM adapters implement `build_chat`, `configure_chat`, `message`, and `tool_call` in addition to complete/stream. The base class supplies a default `identity` and a nil default for `input_budget`. See `sig/phronomy/llm_adapter/base.rbs` for exact keywords and return contracts. Translate SDK-specific exceptions into LLM failures at adapter operation boundaries, preserving the original cause. Do not translate application exceptions or cancellation into unrelated provider failures.
+
+The existing `tool_result_max_size` configuration API and logger are supplied by application composition to neutral RuntimeSettings. Remove references from Tool to the composition factory while preserving default, nil, and scoped-copy semantics. Place RBS in `sig/` and `sig/_private/`, and analyze dependencies based on implementation constants and declaration ownership.
+
+## Progress by r8 item
+
+| Item | This implementation unit | Outstanding work |
 |---|---|---|
-| 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件の三角形レビュー | 再判定未完了 | 図の再解析は判定完了の代わりにはならない |
+| DP01 Context consolidation | Main scope implemented | Broader domain inputs and public operations still require review |
+| DP02 Shared Tool foundation | Shared definition, authorization evaluation, and invocation implemented | Agent FSM bindings and all parent/child authorization rules remain under DP12/P04 |
+| DP03 Execution consolidation | Implemented | This does not complete the review of FSM use across all domains |
+| DP04 Persistence | Not started | Facade removal and shared transaction/participation/outcome-reconciliation APIs |
+| DP05 Domain persistence schemas | Not started | Consolidation of MultiAgent/Workflow storage_contract |
+| DP06 LLM consolidation | Prerequisites only | Full consolidation of llm_contract and llm_adapter |
+| DP07 Consolidation of thin failure directories | Implemented | This is not a redesign of every domain's failure vocabulary |
+| DP08 Composition consolidation | Bindings added only | Physical consolidation of runtime/persistence/agent composition |
+| DP09 Independent Embeddings domain | Not started | Placement independent of vector_store |
+| DP10 Documents | Not started | Loader/splitter relocation |
+| DP11 Decomposition of assembly/concerns | Main scope implemented | Agent-specific processing remains directly under Agent |
+| DP12 Domain execution bindings | Partial, including the Workflow completion boundary | Full separation of Agent/ToolInvocation/Team domain decisions from FSM bindings |
+| DP13 Recovery/Handoff | Not started | Ownership of domain recovery, Persistence outcome reconciliation, and parent/child operations |
+| P02 Persistence participation | Validated in the existing Agent/Context transaction | Outer scopes, savepoints, and public participation APIs across multiple domains |
+| P01/P03-P06 Persistence and parent/child coordination | Not started | The atomicity conditions below must be established |
+| Triangle review: 155 pairs, 393 cases | Reassessment incomplete | Regenerating the diagrams does not substitute for completing the assessment |
 
-NC/F/RMの全項目を「対応済み」とする資料は作成していない。受入可否はこの表の実装単位と同梱テスト証拠に限定する。
+No document claims that every NC/F/RM item has been addressed. Acceptance claims are limited to the implementation units in this table and the accompanying test evidence.
 
-## Persistenceをこの適用単位から外した理由
+## Why Persistence is outside this implementation unit
 
-現在のAgent初回受付は保存transaction内でTeam予約を読む。AgentからTeam内部への参照は最終設計では解消すべきだが、検証を単純に先行呼出へ移すと次の競合が生じる。
+Initial Agent admission currently reads the Team reservation inside the persistence transaction. The final design should eliminate Agent's reference to Team internals, but simply moving validation to an earlier call creates this race:
 
-1. 親側が予約の有効性を確認する。
-2. 別の処理が予約を取り消す。
-3. Agentが新しいtransactionで受付記録を保存し、取消済みの子を開始してしまう。
+1. The parent checks that the reservation is valid.
+2. Another operation cancels the reservation.
+3. Agent saves its admission record in a new transaction and starts the cancelled child.
 
-次の適用単位では、親が所有する予約確認とAgent受付記録を同一scopeで行う参加APIが必要である。親は予約規則、Agentは受付規則、Persistenceは参加とcommit境界を所有する。Agentが親kindをswitchしてTeamを選ぶ現在の逆依存を、新しいcallbackの裏へ隠すだけでは解決にならない。
+The next implementation unit needs a participation API that performs the parent-owned reservation check and records Agent admission within the same scope. The parent owns reservation rules, Agent owns admission rules, and Persistence owns participation and commit boundaries. Merely hiding the current reverse dependency, where Agent switches on parent kind to select Team, behind a new callback would not resolve it.
 
-具体的に未確定なのは、参加操作の公開keyword/返却値、取消との競合条件、commit後のRuntime admission、停止後の同じ子IDによる照会・再開である。Workflowのhalt/finish snapshotだけで任意action内の子実行が耐障害化されるとは扱わない。Workflow→Agent/Teamの具体経路、checkpoint、結果取込一回性をP05で定める。成否不明は単一record一致だけで成功にせず、複数domainの証拠をP06で定める。
+The unresolved details are public participation keywords/return values, races with cancellation, post-commit Runtime admission, and querying/resuming with the same child ID after interruption. Workflow halt/finish snapshots alone do not make child execution inside arbitrary actions durable. P05 must define the concrete Workflow-to-Agent/Team paths, checkpoints, and one-time result incorporation. Unknown outcomes must not be treated as success based on a single matching record; P06 must define evidence across multiple domains.
 
-そのため既存Persistence facade、Team受付検証、予約・子記録のtransaction境界を本変更では改変しない。保証を弱めた仮実装を入れず、次の仕様・実装単位として残す。
+Therefore this change does not alter the existing Persistence facade, Team admission validation, or transaction boundaries for reservations and child records. These remain for the next specification and implementation unit, rather than introducing provisional code with weaker guarantees.
 
-## 解析図の読み方
+## Reading the analysis diagrams
 
-実ソースとRBSから再生成する。従来の水平帯・グループ色・個別module枠を維持し、文字の背景は透過。M33/M41/M44への矢印は表示のみ省略し、JSON・行列・境界判定にはすべて残す。旧IDは再利用せず退役させる。
+Regenerate the diagrams from actual source and RBS. Preserve the existing horizontal bands, group colors, individual module boxes, and transparent text backgrounds. Arrows to M33/M41/M44 are omitted only from the display; retain them in JSON, matrices, and boundary assessments. Retire old IDs instead of reusing them.
 
-これは修正版candidateの実測図であり、全r8完了時の構想図ではない。残る循環・逆依存もそのまま出力する。静的解析で見えない注入先・動的dispatchはRBSだけで完全に証明できない。Engine機構接続とdomain保存の実行テストを併用する。
+These are measured diagrams of the revised candidate, not conceptual diagrams of a completed r8. Include remaining cycles and reverse dependencies. RBS alone cannot fully prove injected targets or dynamic dispatch that static analysis cannot observe. Combine it with execution tests for Engine mechanism bindings and domain persistence.
 
 ```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では次の指定を用いる
+# After committing lib/sig, use this option for an unpublished candidate.
 python tools/architecture/refresh_diagram.py . tmp/architecture-r8-unit1 --candidate
 ```
 
-同梱SVGのSHAは作成用のローカルcandidateを示す。利用者が適用してcommitしたSHAとは異なるため、適用後の図はそのcheckoutで再生成する。Rubyの検証環境、件数、skip理由、未検証環境と適用手順は配布パッケージの検証報告を参照する。
+The SHA in the supplied SVG identifies the local candidate used to generate it. It differs from the SHA created when the user applies and commits the changes, so regenerate the post-application diagrams from that checkout. See the distribution package's verification report for the Ruby environment, test counts, skip reasons, unverified environments, and application procedure.

data/docs/architecture/r8-unit15.md

@@ -1,5 +1,8 @@
 # r8 unit15: Generation contract boundaries
 
+> Historical contract: parser injection/fallback is superseded by
+> [structured output and scope](../architecture/structured-output-and-scope.md).
+
 This responsibility refactor is based on applied unit14, commit
 `97c3d76b35594bb971a60a2932410ddf22e48d3a` (tree
 `c326196212a4ac369294a9ccb936619813e51250`).

data/docs/architecture/r8-unit2.md

@@ -1,55 +1,55 @@
-# r8 unit 2：親の予約確認とAgent受付
+# r8 unit 2: Parent reservation checks and Agent admission
 
-この単位はP02／P03の受付境界を実装する。基準はcore `16e6fcb2dd49836735598525114abfc256d0773e`。r8全体やPersistenceの全面整理の完了ではない。
+This unit implements the P02/P03 admission boundary. The core baseline is `16e6fcb2dd49836735598525114abfc256d0773e`. It does not complete all of r8 or the entire Persistence reorganization.
 
-## 責務と操作
+## Responsibilities and operations
 
-| 担当 | 公開操作・共通規則 | 依存と内部実装 |
+| Owner | Public operations and shared rules | Dependencies and internal implementation |
 |---|---|---|
-| 共通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を渡さない |
+| Shared Persistence | `atomic`, `Transaction#participate`, and `committed?`; validates the same Persistence instance, synchronous thread, active scope, savepoints, and commit acknowledgements | Uses Storage's public transaction/scope rules; does not select Agent, Team, Workflow, or composition components |
+| Agent | `Admission#accept_in`; persists input records, execution identity, Agent admission, and revision updates in the same scope | Uses Agent's persistence component; does not interpret parent kind, Team assignments, subagent snapshots, or Handoff reservations |
+| MultiAgent | `ReservedChildAdmission#admit`; validates parent cancellation, slot, and child ID, and has Agent admission participate in the same scope | Its own persistence component reads the reservation evidence and acquires the required guards |
+| Persistence components | `Agent::Persistence::Admission`, `MultiAgent::Persistence::Reservation` | Uses raw Storage views at this boundary; does not pass raw views to domain operations |
 
-AgentのRuntime admission取得、FSM開始、live状態の反映は既存のExecutionCoordinatorが引き続き所有する。新しいAdmissionはその短い保存フェーズだけであり、Agent実行全体を親のDB transactionへ入れない。通常のアプリは新しい参加クラスを実装・生成する必要がない。
+The existing ExecutionCoordinator continues to own acquiring Agent Runtime admission, starting the FSM, and applying live state. The new Admission covers only the short persistence phase; it does not place the entire Agent execution inside the parent's database transaction. Ordinary applications do not need to implement or instantiate the new participation classes.
 
-`phronomy_admission` は内部の現在の配線であり、Procやオブジェクトを保存しない。永続化するのは従来の相関情報と親子IDだけ。Team／subagent／Handoffの開始・再開担当が現在の参加者を渡す。保存済み実行への再接続はExactExecutionの同一ID照合と復旧規則を維持する。
+`phronomy_admission` is current internal wiring; no Proc or object is persisted. Only the existing correlation information and parent/child IDs are stored. The Team/subagent/Handoff start and resume components supply the current participant. Reconnecting to a persisted execution preserves ExactExecution's same-ID matching and recovery rules.
 
-## 保存順序と失敗
+## Persistence ordering and failures
 
-1. Agentが既存のRuntime受付を取得し、同期workerで保存操作を開始する。
-2. MultiAgentが短い`atomic` scopeを開き、親のguardを取得してから予約を読み直す。
-3. 親の取消・割当・子の識別子を検証する。Agentは同じscopeで入力内容・AgentExecution・AgentRootを保存する。
-4. commit応答が成功した後に、Agent実行担当だけが受付結果を取得し、準備・FSM・live反映を進める。
+1. Agent acquires the existing Runtime admission and begins the persistence operation on a synchronous worker.
+2. MultiAgent opens a short `atomic` scope, acquires the parent guard, and then rereads the reservation.
+3. It validates parent cancellation, assignment, and child identity. Agent stores the input content, AgentExecution, and AgentRoot in the same scope.
+4. Only after a successful commit acknowledgement does the Agent execution component obtain the admission result and continue preparation, FSM execution, and live-state updates.
 
-参加操作の戻り値はcommit成功を意味しない。`accept_in`はnilを返し、Agent内部の`result`は外側のcommitまで利用できない。二重参加、別Persistence、別thread、終了後scopeは拒否する。同じbackendを包む別Persistenceも同一scopeと扱わない。raw backend transactionの中から新しくcommit所有者を名乗ることも拒否する。
+A participation operation's return value does not mean that commit succeeded. `accept_in` returns nil, and the Agent-internal `result` is unavailable until the outer commit. Duplicate participation, a different Persistence instance, a different thread, or an expired scope is rejected. Separate Persistence instances wrapping the same backend are not treated as the same scope. Code inside a raw backend transaction cannot claim to be a new commit owner.
 
-明示的な入れ子はsavepointとして動く。内側が成功しても外側がrollbackした場合は未成立。参加処理中の例外を内側で捕捉しても、失敗したscopeの先行変更をcommitできない。LLM、Tool、scheduler、外部callback、非同期待機を参加処理へ入れない。
+Explicit nesting uses savepoints. Inner success is not committed if the outer transaction rolls back. Even if an exception during participation is caught inside the scope, earlier changes in that failed scope cannot be committed. Do not perform LLM calls, Tool calls, scheduling, external callbacks, or asynchronous waits inside participation operations.
 
-Storageのscope違反は`Persistence::TransactionError`へcause・backtraceを保持して変換する。この名前の変更は、保存成否が既知であるとの宣言ではない。IOError等の成否不明な保存失敗は変換・自動retryせず、既存のAgent復旧規則へ渡す。今回、一般化した保存成否照合APIは追加していない。
+Storage scope violations are translated into `Persistence::TransactionError`, preserving cause and backtrace. This naming change does not assert that the persistence outcome is known. Persistence failures with unknown outcomes, such as IOError, are neither translated nor automatically retried; they pass to existing Agent recovery rules. This unit does not add a generalized persistence-outcome reconciliation API.
 
-## 取消との競合
+## Races with cancellation
 
-TeamはTeamRoot、subagentは親AgentRoot、Handoffはrouting recordをguardとする。PostgreSQLではそのguardの行ロックと既存の条件付き更新によって、取消・変更と子受付を順序付ける。子受付側の通常readだけでは、この保証は成立しなかった。
+Team uses TeamRoot as its guard, subagents use the parent AgentRoot, and Handoff uses the routing record. On PostgreSQL, row locks on the guard and existing conditional updates order cancellation/changes against child admission. Ordinary reads on the child admission path alone did not provide this guarantee.
 
-Handoff取消側は最初に子の状態を観測し、未完了／不在ならroutingをロックして**子の状態を再取得**する。待機中に子受付がcommitした場合、古い「不在」の判断を捨て、受付済みの子へ公開取消を送る。既に終端の実行への取消は従来どおり結果参照として扱う。
+The Handoff cancellation path first observes the child state. If the child is incomplete or absent, it locks routing and **reads the child state again**. If child admission committed while it was waiting, it discards the stale absence observation and sends public cancellation to the admitted child. Cancellation of an already terminal execution continues to act as result access.
 
-InMemoryは共有Monitor、SQLiteはtransactionと書込競合検出、PostgreSQLは行ロックを使用する。SQLiteで競合したtransactionは成功とみなさず、backendの失敗を扱う。分散leaseや外部副作用のexactly-onceは追加しない。実PostgreSQLでの待機順序はexamplesの新しい3件の並行テストで確認する対象であり、InMemory／SQLiteの成功から推定して済ませない。
+InMemory uses a shared Monitor, SQLite uses transactions and write-conflict detection, and PostgreSQL uses row locks. A conflicting SQLite transaction is not considered successful; its backend failure is handled. No distributed lease or exactly-once guarantee for external effects is added. Actual PostgreSQL waiting order is to be checked by the three new concurrency tests in examples; it must not be inferred from successful InMemory/SQLite tests.
 
-## API・ファイル変更
+## API and file changes
 
-- 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規則は変更していない。データ移行は不要。
+- Remove Agent::InitialPreparation's `build_admitted_execution`, its three kinds of parent validation, and its parent-kind branches. Separate shared Agent admission handling from MultiAgent reservation decisions.
+- Place the shared participation framework in `persistence/transaction.rb`, Agent admission in `agent/admission.rb`, and persistence bindings in each domain's existing `persistence/`. No new directory or independent Contract is added.
+- Add synchronous-context `transaction_open?` to the Storage SPI. Implementations inheriting Storage::Backend receive a shared implementation. Custom SPI implementations that do not inherit it must also provide this operation. Update RBS, the SPI snapshot, and duck-typed backend validation.
+- Unify the public type for known Persistence scope failures as `Persistence::TransactionError`; do not add an alias for the old Storage exception. Code using Storage directly continues to use the existing Storage exception.
+- Place RBS in sig and declare participant factories, Agent admission, and MultiAgent dependencies. Track dynamic `phronomy_admission` injection in this document and at its use sites.
+- Separate dependency analysis rules for the Execution boundary from the diagram's revision display name. Add a regression test ensuring that changing the unit name does not disable the prohibition on synchronous-backend dependencies on Execution.
+- Preserve persisted record formats, IDs, and revision rules. No data migration is required.
 
-## 残る課題
+## Outstanding work
 
-`Persistence#transaction`とdomain repositoryの一括窓口は現行利用箇所が残るため、この単位では全面削除していない。互換維持のために新しい旧名aliasを追加したものではないが、P01／DP04の完了条件は未達である。次にdomain照会・保存構成を移し、不要な窓口を利用側と同時に削除する。
+`Persistence#transaction` and the combined domain-repository facade still have callers and are not fully removed in this unit. This does not add new aliases for old names to preserve compatibility, but the P01/DP04 completion conditions remain unmet. Next, move domain queries and persistence composition, then remove unnecessary entry points together with their callers.
 
-MultiAgentの保存担当にはAgentのexecution／Handoff repositoryへの参照が残る。予約検証の所有者は整理したが、親子の公開投影・認可照会・結果取込まで隠蔽したとは扱わない。P04／F02／F03の残課題として、Agentが公開する操作と、MultiAgentが所有すべき保存形式を確定する。一般的なmetadata getterを足すだけの解決にはしない。
+MultiAgent's persistence component still references Agent execution/Handoff repositories. Ownership of reservation validation has been clarified, but this does not mean that public parent/child projections, authorization queries, and result incorporation have all been encapsulated. Under the remaining P04/F02/F03 work, establish the operations Agent should expose and the persistence formats MultiAgent should own. Adding a generic metadata getter alone is not a solution.
 
-Agent／TeamのFSM接続、Workflowのdurableな子連携（P05）、複数記録の保存成否照合（P06）、残りの配置整理、155組・393件の意味的再判定も残る。今回のSVGは実装候補を描き、全体の循環解消を示す構想図にはしない。
+Agent/Team FSM bindings, durable Workflow child coordination (P05), reconciliation of persistence outcomes across multiple records (P06), the remaining layout reorganization, and semantic reassessment of 155 pairs/393 cases also remain outstanding. The SVG for this unit depicts the implementation candidate, not a conceptual graph claiming that all cycles have been eliminated.

data/docs/architecture/r8-unit7.md

@@ -6,7 +6,8 @@ all of C04, C06 or the overall target complete.
 
 | Owner | Responsibility after this change |
 | --- | --- |
-| Agent InvocationTransitions | Phase vocabulary, ordered automatic/external transitions, guard evaluation, iteration bound |
+| Agent IterationBudget | Logical LLM-call limit over durable AgentExecution records; see [iteration budget](agent-iteration-budget.md) |
+| Agent InvocationTransitions | Phase vocabulary, ordered automatic/external transitions, guard evaluation, automatic-chain safety bound |
 | Agent InvocationActions | Prepared input, LLM dispatch, Tool batch orchestration and result/event interpretation |
 | Agent ExecutionCoordinator / RecoveryCoordinator | Admission, durable preparation, approval, terminal outcome, recovery and causal revision checks |
 | Agent ExecutionEnvironment | Private process-local connection required by the Agent framework; session construction/registration, serial owner and operation submission |