phronomy 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '095ac1376e77f34201dceeafec7dc114340aa2cae7cd8f1bb2bb7c2552e64e87'
-  data.tar.gz: 4d900c3bdc20e3fb0210046daffc4d78d1b990f118281c04037cc45beca2d699
+  metadata.gz: f097c81530a33bd631974866ff26a0d2ec8b4793286c6dfa0bb0facaac4fdd83
+  data.tar.gz: 80b9980737c80446f660d9a058aa1b898bdcdec452e517764261c386c32a1e78
 SHA512:
-  metadata.gz: 3108c48424885f72ea256e6c7cd7dfa8a7230647727f288f9fce840ee9309a51b523e64748663a7d1341e88b0c05cfe5432cb91a521039b16f28b0e2c14a4714
-  data.tar.gz: 51795e8c019cb92d8a17eadb864b726f9359ed1c963b06acfb52cb7440b99234755ad2c7e169a5afb8e5958ea45b99635d9035eea4d3c4ceb84ac4d554fdc814
+  metadata.gz: 2cacf04ecea168021b36835f12901723380a7a908d0173f23b564e9bb67d4f85cf46bf958949fd4257043393234ef5acc7e8d9cecdcf68beac61b0c7ce454084
+  data.tar.gz: c7f7b1d9cbcd54d0d0d9bb7583e5587ecadfafa987788f44e8c8abc0f9fa75241092d63a543669b55a6837fc1c2c09c102cf514578b6c266b2c85ff17d2ba2cc

data/.mutant.yml

@@ -9,14 +9,14 @@ matcher:
   subjects:
     - Phronomy::WorkflowContext
     - Phronomy::WorkflowRunner
-    # Phronomy::Tool::Base is a public constant alias to this same Class object.
-    # Use the implementation canonical name returned by Class#name for Mutant.
-    - Phronomy::Agent::Context::Capability::Base
+    - Phronomy::Tool::Base
+    - Phronomy::Tool::Schema
     - Phronomy::LlmContextWindow::TokenBudget
-    - Phronomy::Agent::ContextAssembler
-    - Phronomy::Agent::ContextPolicies::Default
-    - Phronomy::Agent::ContextPolicyInputBuilder
-    - Phronomy::Agent::ContextPlanValidator
-    - Phronomy::Agent::HandoffPolicy
-    - Phronomy::Agent::HandoffProjection
+    - Phronomy::Context::Assembly
+    - Phronomy::Agent::ContextPreparation
+    - Phronomy::Context::DefaultPolicy
+    - Phronomy::Context::ContextPolicyInputBuilder
+    - Phronomy::Context::ContextPlanValidator
+    - Phronomy::MultiAgent::HandoffPolicy
+    - Phronomy::Agent::TransferProjection
     - Phronomy::VectorStore::InMemory

data/CHANGELOG.md

@@ -12,6 +12,58 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+### r8 first implementation unit (breaking, unreleased)
+
+- Move Context policy/plan/manifest/budget/prompt operations into `Phronomy::Context`.
+  Agent retains snapshot, journal and lifecycle ownership. Manifest and execution
+  references remain written within the same transaction.
+- Make `Tool::Base` the actual implementation; move common definition and
+  authorization operations into Tool. Remove the old Agent Context namespace.
+- Move chat construction and SDK failure translation into the LLM adapter.
+  Custom synchronous adapters must implement the expanded construction SPI.
+- Unite execution contracts and services in `execution/`; move FSM values and
+  scheduling bindings to Engine, observation to Tracing. Keep result/control
+  rules independent of Engine startup. Update Ruby/RBS analysis and diagrams.
+- Remove empty contract-only subdivisions and old API aliases. This unit does
+  not complete r8 Persistence, parent admission or all domain FSM separation.
+  See [the scope and migration report](docs/architecture/r8-unit1.md).
+
+### Changed
+
+- Add public Beta `Storage::AsyncClient#transaction_async` and route 16 existing
+  durable Agent/Workflow/coordination execution units through its private submit
+  boundary. Preserve transaction/savepoint, result reconciliation and admission
+  policy; do not add cancellation or timeout to existing terminal writes.
+- Move StoredContents into `content_store/backends/` without changing its
+  constant or behavior. Complete P4; see the
+  [Storage client guide](docs/migrations/storage-async-client.md).
+- Preserve transparent text panels and module outlines in generated diagrams.
+  Hide arrows into M33/M41/M44 as a display choice; keep their measured source
+  dependencies, evidence and complete matrix.
+
+- **Beta API receiver migration:** move VectorStore `add_async`, `search_async`,
+  `remove_async`, `clear_async` and Embeddings `embed_async` onto the public
+  feature-specific `AsyncClient` objects. Synchronous backend methods and
+  concrete class names remain unchanged. Remove the inherited async methods
+  and `VectorStore::AsyncBackend`; see the
+  [migration guide](docs/migrations/vector-async-clients.md).
+- Split VectorStore/Embeddings implementations into collapsed `backends/`
+  directories. Synchronous RBS uses structural cancellation; separate client
+  signatures retain TaskResult and the full execution token. Complete P3 and
+  remove the remaining backend-to-Engine edges from the measured graph.
+
+- Separate the synchronous LLMAdapter SPI, RubyLLM implementation and internal
+  AsyncClient. Adapter authors implement only `complete` and `stream`; default
+  configuration, provider behavior, admission/cancellation and Agent event
+  delivery remain unchanged. See
+  [ADR-059](docs/decisions/059-backend-contracts-and-async-clients.md).
+- Separate responsibility groups from the diagram's B1-B6 display layers. Add
+  the source-derived SVG/matrix generator and Architecture CI boundary gate;
+  retain individual module boxes, stable module IDs and the earlier horizontal
+  layer layout with topical columns. Separated Contracts belong in B5 beside
+  the independent Engine group; clients, implementations and pending mixed
+  backends are displayed in B4. Storage/ContentStore migration remains pending.
+
 ---
 
 ## [0.27.0] - 2026-09-24

data/CONTRIBUTING.md

@@ -219,14 +219,14 @@ The authoritative subject list is `.mutant.yml`. It currently includes:
 
 - `Phronomy::WorkflowContext`
 - `Phronomy::WorkflowRunner`
-- `Phronomy::Agent::Context::Capability::Base`
+- `Phronomy::Tool::Base`
 - `Phronomy::LlmContextWindow::TokenBudget`
-- `Phronomy::Agent::ContextAssembler`
-- `Phronomy::Agent::ContextPolicies::Default`
-- `Phronomy::Agent::ContextPolicyInputBuilder`
-- `Phronomy::Agent::ContextPlanValidator`
-- `Phronomy::Agent::HandoffPolicy`
-- `Phronomy::Agent::HandoffProjection`
+- `Phronomy::Agent::ContextPreparation`
+- `Phronomy::Context::DefaultPolicy`
+- `Phronomy::Context::ContextPolicyInputBuilder`
+- `Phronomy::Context::ContextPlanValidator`
+- `Phronomy::MultiAgent::HandoffPolicy`
+- `Phronomy::Agent::TransferProjection`
 - `Phronomy::VectorStore::InMemory`
 
 The nightly mutation matrix mirrors this authoritative list so each subject can
@@ -235,7 +235,7 @@ configuration-consistency guard that fails if the nightly subject set diverges
 from `.mutant.yml`.
 
 The Tool mutation subject intentionally uses
-`Phronomy::Agent::Context::Capability::Base`, which is the implementation
+`Phronomy::Tool::Base`, which is the implementation
 canonical name returned by the single Class object's runtime `Class#name`.
 `Phronomy::Tool::Base` is the public facade constant alias to that same Class
 object; it is not a second Tool base class.

data/README.md

@@ -8,7 +8,11 @@
 
 **Phronomy** is a Ruby AI agent framework for stateful Agents, Workflows, Tools,
 context management, filtering, tracing, and multi-agent coordination. Large Language
-Model (LLM) access is provided through [RubyLLM](https://github.com/crmne/ruby_llm).
+Model (LLM) operations use `Phronomy::LLMAdapter`; the default backend uses
+[RubyLLM](https://github.com/crmne/ruby_llm). Custom backends implement the
+[SDK-independent LLM contract](docs/migrations/r8-unit6.md).
+Tool declarations and argument validation belong to `Phronomy::Tool`, independently
+of the selected LLM backend.
 
 Phronomy is pre-1.0. Pin to a released gem version for production use rather than
 tracking `main` directly.
@@ -16,7 +20,7 @@ tracking `main` directly.
 ## Core concepts
 
 - **Agent** — stateful, persistence-backed LLM agent with canonical execution history.
-- **Persistence** — unified durable backend for Agent state and Workflow `workflow_states`.
+- **Persistence** — shared atomic scopes with domain-owned Agent/Team stores and Workflow checkpoints.
 - **Workflow** — state-machine-driven application workflow with explicit events and wait states.
 - **Tool / Capability** — callable application capability exposed to an Agent; application-defined Tools subclass `Phronomy::Tool::Base`.
 - **Multi-Agent Handoff** — semantic Source-to-Target responsibility transfer with policy-bounded Context projection and persisted active responsibility and exact Target recovery within one Persistence domain.
@@ -88,7 +92,7 @@ puts result[:output]
 ```
 
 `Phronomy::Tool::Base` is the public authoring name for the existing Tool base
-class. The legacy `Phronomy::Agent::Context::Capability::Base` constant remains
+class. The legacy `Phronomy::Tool::Base` constant remains
 valid for compatibility.
 
 For non-blocking top-level use, call `invoke_async` and keep the returned
@@ -155,6 +159,8 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 - [MCP client](docs/mcp-client.md) — Model Context Protocol (MCP) integration and supported schema subset.
 - [Migration from 0.15-era APIs](docs/migrations/0.15.md).
 - [0.16 cleanup migration](docs/migrations/0.16.md).
+- [r8 persistence boundary migration](docs/architecture/r8-unit3.md) — domain stores, shared scopes, and removed facade APIs.
+- [Persistence failure contract migration](docs/migrations/persistence-failure-contracts.md) — domain rescue clauses and unchanged raw backend errors.
 - [0.19 unified Persistence migration](docs/migrations/0.19.md).
 - [0.22 semantic Multi-Agent Handoff migration](docs/migrations/0.22.md).
 - [Architecture Decision Records](docs/decisions/) — design rationale and superseding decisions.

data/benchmark/bench_agent_invoke.rb

@@ -19,49 +19,21 @@ require_relative "../lib/phronomy"
 # Shared stubs
 # ---------------------------------------------------------------------------
 
-module BenchAgentMessage
-  def self.assistant(content = "done")
-    RubyLLM::Message.new(
-      role: :assistant, content: content,
-      tokens: RubyLLM::Tokens.new(input: 5, output: 5, cache_read: 0, cache_write: 0)
-    )
-  end
-end
-
-# A minimal stub Chat that returns a pre-built response immediately.
-class BenchStubChat
-  attr_reader :messages
-
+# A stub backend that preserves the adapter's validation/cancellation template.
+class BenchStubLLMAdapter < Phronomy::LLMAdapter::Base
   def initialize(response)
     @response = response
-    @messages = []
-  end
-
-  def with_instructions(_, **_options) = self
-  def with_tools(*) = self
-  def with_temperature(_) = self
-  def with_cache_instructions(_) = self
-  def with_output_schema(_) = self
-  def last_message = @response
-
-  def after_message(&block)
-    @after_message = block
-    self
   end
 
-  def ask(_)
-    complete
-  end
+  protected
 
-  def complete
-    @messages << @response
-    @after_message&.call(@response)
+  def perform_complete(request, cancellation_token:)
     @response
   end
 end
 
 # A stub tool that does nothing but conforms to the Tool::Base interface.
-class BenchNullTool < Phronomy::Agent::Context::Capability::Base
+class BenchNullTool < Phronomy::Tool::Base
   description "No-op benchmark tool"
   param :x, type: :string, desc: "input"
 
@@ -74,38 +46,41 @@ end
 # Agent classes
 # ---------------------------------------------------------------------------
 
-BENCH_RESP = BenchAgentMessage.assistant("benchmark complete")
+BENCH_RESP = Phronomy::LLMAdapter::Response.new(
+  content: "benchmark complete",
+  usage: Phronomy::LLMAdapter::TokenUsage.new(input: 5, output: 5, cached: 0, cache_creation: 0)
+)
 
 bench_minimal_class = Class.new(Phronomy::Agent::Base) do
   agent_definition id: "bench-minimal", version: 1
   model "stub-model"
-
-  define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end
 
 bench_tool_class = Class.new(Phronomy::Agent::Base) do
   agent_definition id: "bench-tool", version: 1
   model "stub-model"
   tools(BenchNullTool => nil)
-
-  define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end
 
 AGENT_INVOKE_ITERATIONS = 200
-BENCH_AGENTS_MINIMAL = Array.new(AGENT_INVOKE_ITERATIONS) { bench_minimal_class.new }.freeze
-BENCH_AGENTS_TOOLS = Array.new(AGENT_INVOKE_ITERATIONS) { bench_tool_class.new }.freeze
-
-puts "=== bench_agent_invoke ==="
-Benchmark.bm(50) do |x|
-  x.report("Agent#invoke — fresh, no tools, #{AGENT_INVOKE_ITERATIONS} iters") do
-    BENCH_AGENTS_MINIMAL.each do |agent|
-      agent.invoke("ping")
+
+Phronomy.with_configuration do |config|
+  config.llm_adapter = BenchStubLLMAdapter.new(BENCH_RESP)
+  bench_agents_minimal = Array.new(AGENT_INVOKE_ITERATIONS) { bench_minimal_class.new }.freeze
+  bench_agents_tools = Array.new(AGENT_INVOKE_ITERATIONS) { bench_tool_class.new }.freeze
+
+  puts "=== bench_agent_invoke ==="
+  Benchmark.bm(50) do |x|
+    x.report("Agent#invoke — fresh, no tools, #{AGENT_INVOKE_ITERATIONS} iters") do
+      bench_agents_minimal.each do |agent|
+        agent.invoke("ping")
+      end
     end
-  end
 
-  x.report("Agent#invoke — fresh, tool-aware, #{AGENT_INVOKE_ITERATIONS} iters") do
-    BENCH_AGENTS_TOOLS.each do |agent|
-      agent.invoke("ping")
+    x.report("Agent#invoke — fresh, tool-aware, #{AGENT_INVOKE_ITERATIONS} iters") do
+      bench_agents_tools.each do |agent|
+        agent.invoke("ping")
+      end
     end
   end
 end

data/benchmark/bench_context_assembler.rb

@@ -14,7 +14,7 @@ module BenchContextAssembler
   module_function
 
   def provenance
-    Phronomy::Agent::ContextPolicyInput::Provenance.new(origin: :journal)
+    Phronomy::Context::ContextPolicyInput::Provenance.new(origin: :journal)
   end
 
   def policy_input(item_count)
@@ -22,13 +22,13 @@ module BenchContextAssembler
     conversation = []
     item_count.times do |index|
       if (index % 10).zero?
-        knowledge << Phronomy::Agent::ContextPolicyInput::KnowledgeItem.new(
+        knowledge << Phronomy::Context::ContextPolicyInput::KnowledgeItem.new(
           id: "knowledge-#{index}", kind: :knowledge, role: :user,
           content: "knowledge #{index}", content_format: :text,
           estimated_tokens: 8, required: false, provenance: provenance, metadata: {}
         )
       else
-        conversation << [Phronomy::Agent::ContextPolicyInput::ConversationItem.new(
+        conversation << [Phronomy::Context::ContextPolicyInput::ConversationItem.new(
           id: "message-#{index}", kind: :external_message, role: :user,
           content: "message #{index}", content_format: :text,
           sequence: index, estimated_tokens: 8, required: false,
@@ -38,7 +38,7 @@ module BenchContextAssembler
       end
     end
 
-    Phronomy::Agent::ContextPolicyInput.new(
+    Phronomy::Context::ContextPolicyInput.new(
       agent_id: "bench-agent", execution_id: "bench-execution",
       call_sequence: 2, call_mode: :complete,
       instruction: [], knowledge: knowledge, tools: [], conversation: conversation,
@@ -50,7 +50,7 @@ module BenchContextAssembler
   end
 
   def assembler_fixture
-    persistence = Phronomy::Persistence.in_memory
+    persistence = Phronomy::PersistenceComposition.in_memory.agent
     agent_class = Class.new(Phronomy::Agent::Base) do
       agent_definition id: "bench-manifest-context-assembler", version: 1
       # Resolve capabilities from RubyLLM's bundled registry; no provider call.
@@ -86,9 +86,10 @@ module BenchContextAssembler
     )
 
     [
-      Phronomy::Agent::ContextAssembler.new(agent: agent, persistence: persistence),
+      Phronomy::Agent::ContextPreparation.new(agent: agent, persistence: persistence),
       root,
-      execution
+      execution,
+      persistence
     ]
   end
 end
@@ -97,7 +98,7 @@ puts "Typed Context Policy benchmark"
 puts "Ruby #{RUBY_VERSION} on #{RUBY_PLATFORM}"
 puts "=" * 72
 
-policy = Phronomy::Agent::ContextPolicies::Default.instance
+policy = Phronomy::Context::DefaultPolicy.instance
 policy_inputs = [10, 100, 1_000].to_h do |count|
   [count, BenchContextAssembler.policy_input(count)]
 end
@@ -110,15 +111,17 @@ Benchmark.bm(46) do |x|
     end
   end
 
-  assembler, root, execution = BenchContextAssembler.assembler_fixture
-  x.report("ContextAssembler prepare/finalize x500") do
+  assembler, root, execution, persistence = BenchContextAssembler.assembler_fixture
+  x.report("Context prepare/store x500") do
     500.times do
       prepared = assembler.prepare_initial(
         input: "benchmark input",
         agent_root: root,
         execution: execution
       )
-      assembler.finalize(prepared)
+      persistence.transaction do |tx|
+        Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents)
+      end
     end
   end
 end

data/benchmark/bench_regression.rb

@@ -69,7 +69,7 @@ end
 # ---------------------------------------------------------------------------
 # Target 3: Tool::Base#params_schema generation (10 params)
 # ---------------------------------------------------------------------------
-tool_class = Class.new(Phronomy::Agent::Context::Capability::Base) do
+tool_class = Class.new(Phronomy::Tool::Base) do
   description "Test tool with 10 params"
   param :p1, type: :string, desc: "param 1"
   param :p2, type: :string, desc: "param 2"

data/benchmark/bench_tool_schema.rb

@@ -7,7 +7,7 @@
 require "benchmark"
 require_relative "../lib/phronomy"
 
-class BenchTool10Params < Phronomy::Agent::Context::Capability::Base
+class BenchTool10Params < Phronomy::Tool::Base
   description "A tool with 10 parameters for benchmarking purposes"
   param :param1, type: :string, desc: "First parameter"
   param :param2, type: :integer, desc: "Second parameter"

data/docs/architecture/agent-chat-and-state-ownership.md

@@ -1,5 +1,11 @@
 # Agent Chat and explicit state ownership (R09, second slice)
 
+> Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
+> adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
+> construction/interception; Tool owns canonical schema validation. See
+> `docs/architecture/r8-unit6.md` and `docs/migrations/r8-unit6.md`.
+
+
 ## Purpose and clients
 
 Agent::Base is the declaration and lifecycle facade used by application Agent
@@ -62,7 +68,7 @@ hook retains application/test overrides of apply_instructions and Orchestrator's
 prepare_tool_class(invocation:) cooperation. Moving it into a builder receiving
 the entire Agent would merely introduce callbacks back into Base.
 
-AgentInvocationSessionBuilder and InvocationRestorer keep using the same hooks.
+InvocationActions and EngineSessionBuilder and InvocationRestorer keep using the same hooks.
 Saved config is authoritative during recovery; current class declarations do
 not overwrite it. A failure stops installation at that operation, propagates
 the same error and does not install later Tools/messages. No new Chat cache,

data/docs/architecture/agent-transition-ownership.md

@@ -1,89 +1,13 @@
-# Agent invocation transition ownership
-
-## Role and scope
-
-An Agent invocation moves between preparation, Provider calls, Tool processing,
-approval suspension and completion. Three collaborators need the same policy:
-AgentInvocation consumes external payloads; PhaseMachineBuilder creates the
-executable state machine; AgentInvocationSessionBuilder configures FSMSession's
-advance, wait and terminal boundaries. Independently maintained event lists and
-transition copies could disagree about what the current phase can accept.
-
-Refactor 39 gives that shared policy one private owner, InvocationTransitions in
-agent/execution. This is Agent data in the existing transition Hash format, not
-a new cross-feature DSL or Engine extension. It is not a new execution object.
-
-## Ownership and reading order
-
-| Owner | Responsibility |
-|---|---|
-| InvocationTransitions | Initial phase, declared/automatic/approval-wait states, Tool event vocabulary and ordered external transition definitions. |
-| PhaseMachineBuilder | Translate those external definitions to state_machines; retain automatic state_completed transitions and synchronous entry-action validation. |
-| AgentInvocationSessionBuilder | Assemble the invocation, event sink, entry actions and machine; pass shared state and transition metadata to FSMSession. |
-| AgentInvocation | Apply payloads and expose the current guard predicates; use the shared Tool event vocabulary. |
-| FSMSession | Generic advancement, event delivery and wait/terminal handling. No Agent-specific decisions. |
-
-Read the policy table for legal external sources and guard priority, the machine
-builder for execution mechanics, and the session builder for action wiring.
-The EXTERNAL_EVENTS Hash, each transition array and each row are frozen so one
-session cannot edit another session's policy. Guard lambdas contain no captured
-invocation state; they inspect the context supplied at transition time.
-Old private constants and the external_events factory are removed without aliases.
-
-## Preserved event and phase contract
-
-The six Tool events are authorized, approval_required, completed, failed,
-rejected and cancelled, each with the tool_ prefix. Each moves waiting_for_tools
-to evaluating_tools. LLM completion from calling_llm tries these in order:
-
-1. callback_failed? to failed;
-2. handoff_failed? to failed;
-3. handoff_requested? to handed_off;
-4. tool_call_pending? to starting_tools;
-5. unconditional fallback to output_filtering.
-
-Guards short-circuit. A nil context skips guarded rows and takes the fallback;
-guard exceptions propagate unchanged. Each evaluation uses the latest context,
-without caching a selected destination. Session applies the event payload first.
-
-LLM failure/setup failure leads from calling_llm to failed. Tool setup failure
-leads from dispatching_tools to failed, while tool_dispatch_prepared returns it
-to evaluating_tools. Resume moves suspended to waiting_for_tools. Application
-callback failure is accepted from the existing nine active phases only.
-
-Automatic phases remain idle, filtering_input, building_context, starting_tools,
-evaluating_tools, recording_tool_results and output_filtering. calling_llm,
-waiting_for_tools and dispatching_tools wait for external events. suspended ends
-a segment with halted; resume uses a fresh Session identity. The four declared
-terminal phases remain handed_off, completed, blocked and failed.
-
-FSMSession reads only the from field when determining external-event admission
-and waiting. It does not execute metadata guards or choose their destinations;
-state_machines does that. Known-but-undeclared and unknown events retain their
-existing error behavior; context-consumed stale events retain their early exit.
-The internal order of event registration now follows the shared table. Transition
-order within each event, which determines behavior, is preserved. The generated
-machine's private event-enumeration order is not a supported public contract.
-
-## Verification and limits
-
-Independent behavioral tests run on both Refactor 38 and the candidate: all 195
-external-event/source-state combinations, all sixteen LLM condition combinations
-including short-circuit order, nil context and guard exceptions, fifteen Session
-boundaries, context-before-guard ordering, approval suspension/resume/dispatch,
-and invalid source-state handling. Existing Agent, causal durability, Handoff,
-Workflow and Engine tests continue to cover their collaborating behavior.
-
-The candidate also runs the full core/integration suites, offline examples and
-real SQLite, API/SPI snapshots, RBS, style, annotations and isolated gem checks.
-No SQL, stored format, entry action implementation, Tool restoration, cancellation
-or Coordinator sequencing is changed. The new contract tests isolate entry actions
-and do not claim live Provider coverage. Live PostgreSQL/LLM and remote CI are
-not executed for this candidate. Refactor 39 was independently verified after application at core 4d57614a,
-tree 654241da4b2b7f32d988602d28127bc1fa155641. All 10 files and the full tree
-matched, and core/integration/examples/SQLite/API/type/gem checks passed.
-The published SVG is applied39-01.
-
-R06 is applied and complete. R07 now has a Refactor 40 candidate; R08/D08, R09
-and R10 remain afterward. R09's inheritance behavior and R10's action names
-are not altered by the transition-ownership work.
+# Agent transition ownership (r8 unit 7)
+
+InvocationTransitions owns both automatic and external transitions, including
+ordered guard evaluation. InvocationActions owns Agent entry operations.
+EngineSessionBuilder configures FSMSession using those definitions;
+PhaseMachineBuilder adapts them to state_machines without defining progress rules.
+ExecutionCoordinator and RecoveryCoordinator retain durable decisions and use
+the Agent-owned ExecutionEnvironment port for execution connection.
+
+See [r8 unit 7](r8-unit7.md) and [ADR-067](../decisions/067-agent-progress-and-engine-connection.md).
+Existing event source validation, callback failure priority, short-circuiting,
+Tool outcome priority, suspended/wait/terminal boundaries and session incarnation
+rules are preserved. Agent's Tool child FSM is still a separate remaining task.