phronomy 0.26.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd6beeb52633381ff9e249ec18a1dc422234c78e44f479e3549cd3c54591ab04
-  data.tar.gz: 6528144759933b359d2303b1499b678cbd4eb0c747ca9966f0c6542effb28196
+  metadata.gz: f097c81530a33bd631974866ff26a0d2ec8b4793286c6dfa0bb0facaac4fdd83
+  data.tar.gz: 80b9980737c80446f660d9a058aa1b898bdcdec452e517764261c386c32a1e78
 SHA512:
-  metadata.gz: 307b601d09f6113282eef52f3e547d259e728adf0ba9ac481e3d84dc99583b8510ad779c71e0abee8c78f180b3786d6eacb3fea66723432d93f523e7f4be756a
-  data.tar.gz: 6aed95a5486eaaa792e25ad4d058ebc804278dfa2bf648f216d120256154f7f1cccba86c056ec5176f98556f16e7b835c7102dd0129da5474f9ce93f221cbae8
+  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,98 @@ 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
+
+### Changed
+
+- Separate application Runtime reset and configuration replacement into
+  `runtime_composition/global_runtime.rb`. Configuration access no longer owns
+  Runtime lifecycle control; the reset API, shutdown ordering, timeout behavior,
+  and configuration defaults are unchanged. See
+  [ADR-039](docs/decisions/039-runtime-configuration-lifecycle-ownership.md).
+- Group root implementations and entry-point exceptions by responsibility:
+  common definitions, Engine/FSM execution contracts, Recovery, Workflow,
+  Agent lifecycle contracts, LLM contracts, configuration, and feature APIs.
+  Preserve public constant names, API signatures, stored formats, and lifecycle
+  loading. Reserve the direct source root for version and namespace/loading
+  files; share the three equivalent immutable-copy helpers. See
+  [ADR-038](docs/decisions/038-responsibility-based-source-layout.md).
+- Move the shared `Phronomy::Error` base exception to `common/error.rb` and
+  define ownership rules for general common definitions. The public constant,
+  subclass hierarchies, and rescue behavior are preserved. See
+  [ADR-037](docs/decisions/037-common-definition-ownership.md).
+- Group Context Policy and hook contracts, values, Manifest representation,
+  and Plan validation under `agent/context_contract/`. Zeitwerk collapses the
+  directory so the existing `Phronomy::Agent` constant names, Policy/hook
+  protocols, and Manifest format remain unchanged. Agent execution and Context
+  assembly retain their existing responsibilities. See
+  [ADR-036](docs/decisions/036-context-contract-ownership.md).
+- Move the internal `Phronomy::Agent::ToolExecutor` to
+  `Phronomy::Agent::Context::Capability::ToolExecutor`, alongside the default
+  Tool invocation contract, without an alias for the old internal constant.
+  Public Tool names, `call_async` arguments, execution modes, Runtime routing,
+  and Agent-owned authorization/result handling are preserved. See
+  [ADR-035](docs/decisions/035-tool-executor-capability-ownership.md).
+- Move `Phronomy::Agent::HandoffRunner` to
+  `Phronomy::MultiAgent::HandoffRunner` without a compatibility alias on the
+  architecture refactoring branch. Handoff edges and Policy remain in Agent;
+  execution, persistence formats, cancellation and recovery behavior are unchanged.
+  See [the migration guide](docs/migrations/handoff-runner-multi-agent.md).
+
 ---
 
 ## [0.26.0] - 2026-09-14

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.
@@ -45,6 +49,10 @@ Then run:
 bundle install
 ```
 
+This refactoring branch requires RubyLLM 2.0.x. See the
+[RubyLLM 2 and token-ownership migration](docs/architecture/rubyllm-2-token-ownership.md)
+for removed input-budget overrides and the in-flight Tool-manifest upgrade boundary.
+
 Configure RubyLLM with the provider credentials and transport policy required by
 your application. Phronomy does not add another LLM transport retry/timeout layer.
 
@@ -84,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
@@ -151,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/VERIFY.sh

@@ -21,9 +21,9 @@ required_files=(
   docs/decisions/024-event-loop-single-writer-agent-runtime.md
   docs/decisions/025-process-local-agent-ownership-and-runtime-admission.md
   docs/decisions/026-workflow-runtime-admission-and-durable-terminal-barrier.md
-  lib/phronomy/workflow.rb
-  lib/phronomy/workflow_context.rb
-  lib/phronomy/workflow_runner.rb
+  lib/phronomy/workflow/execution/workflow.rb
+  lib/phronomy/workflow/execution/workflow_context.rb
+  lib/phronomy/workflow/execution/workflow_runner.rb
   lib/phronomy/engine/event_loop.rb
   lib/phronomy/engine/fsm_session.rb
   lib/phronomy/persistence/in_memory.rb
@@ -38,16 +38,16 @@ required_files=(
   spec/phronomy/persistence/initial_format_migration_spec.rb
   lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
   spec/phronomy/workflow_identity_contract_spec.rb
-  lib/phronomy/invocation_context.rb
+  lib/phronomy/engine/invocation_context.rb
   lib/phronomy/agent/async_event_api.rb
   lib/phronomy/agent/execution_coordinator.rb
   lib/phronomy/agent/journal_record.rb
   lib/phronomy/agent/context_assembler.rb
-  lib/phronomy/agent/context_policy.rb
-  lib/phronomy/agent/context_policy_input.rb
+  lib/phronomy/agent/context_contract/context_policy.rb
+  lib/phronomy/agent/context_contract/context_policy_input.rb
   lib/phronomy/agent/context_policy_input_builder.rb
-  lib/phronomy/agent/context_plan.rb
-  lib/phronomy/agent/context_plan_validator.rb
+  lib/phronomy/agent/context_contract/context_plan.rb
+  lib/phronomy/agent/context_contract/context_plan_validator.rb
   lib/phronomy/agent/context_policies/default.rb
   spec/phronomy/agent/context_policy_architecture_regression_spec.rb
   lib/phronomy/agent/agent_invocation.rb
@@ -68,7 +68,7 @@ required_files=(
   spec/phronomy/workflow/admission_spec.rb
   spec/phronomy/workflow/live_signal_spec.rb
   spec/phronomy/workflow/transition_action_spec.rb
-  lib/phronomy/generator_verifier.rb
+  lib/phronomy/generation/generator_verifier.rb
   spec/phronomy/generator_verifier_spec.rb
   spec/integration/subgraph_parallel_agent_tool_spec.rb
   lib/phronomy/tracing/base.rb
@@ -87,11 +87,11 @@ required_files=(
   spec/phronomy/fault_injection_advanced_spec.rb
   spec/phronomy/persistence_architecture_regression_spec.rb
   lib/phronomy/agent/base.rb
-  lib/phronomy/agent_already_exists_error.rb
-  lib/phronomy/agent_purged_error.rb
+  lib/phronomy/agent/lifecycle_contract/agent_already_exists_error.rb
+  lib/phronomy/agent/lifecycle_contract/agent_purged_error.rb
   lib/phronomy/engine/runtime/agent_ownership_registry.rb
   lib/phronomy/agent/agent_root.rb
-  lib/phronomy/agent/llm_input_build_context.rb
+  lib/phronomy/agent/context_contract/llm_input_build_context.rb
   lib/phronomy/agent/shared_state.rb
   spec/phronomy/agent/base_spec.rb
   spec/phronomy/agent_spec.rb
@@ -119,9 +119,9 @@ done
 
 syntax_files=(
   spec/phronomy/architecture_governance_spec.rb
-  lib/phronomy/workflow.rb
-  lib/phronomy/workflow_context.rb
-  lib/phronomy/workflow_runner.rb
+  lib/phronomy/workflow/execution/workflow.rb
+  lib/phronomy/workflow/execution/workflow_context.rb
+  lib/phronomy/workflow/execution/workflow_runner.rb
   lib/phronomy/engine/event_loop.rb
   lib/phronomy/engine/fsm_session.rb
   lib/phronomy/persistence/in_memory.rb
@@ -135,16 +135,16 @@ syntax_files=(
   spec/phronomy/persistence/initial_format_migration_spec.rb
   lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
   spec/phronomy/workflow_identity_contract_spec.rb
-  lib/phronomy/invocation_context.rb
+  lib/phronomy/engine/invocation_context.rb
   lib/phronomy/agent/async_event_api.rb
   lib/phronomy/agent/execution_coordinator.rb
   lib/phronomy/agent/journal_record.rb
   lib/phronomy/agent/context_assembler.rb
-  lib/phronomy/agent/context_policy.rb
-  lib/phronomy/agent/context_policy_input.rb
+  lib/phronomy/agent/context_contract/context_policy.rb
+  lib/phronomy/agent/context_contract/context_policy_input.rb
   lib/phronomy/agent/context_policy_input_builder.rb
-  lib/phronomy/agent/context_plan.rb
-  lib/phronomy/agent/context_plan_validator.rb
+  lib/phronomy/agent/context_contract/context_plan.rb
+  lib/phronomy/agent/context_contract/context_plan_validator.rb
   lib/phronomy/agent/context_policies/default.rb
   spec/phronomy/agent/context_policy_architecture_regression_spec.rb
   lib/phronomy/agent/agent_invocation.rb
@@ -177,7 +177,7 @@ syntax_files=(
   spec/phronomy/workflow/admission_spec.rb
   spec/phronomy/workflow/live_signal_spec.rb
   spec/phronomy/workflow/fsm_session_spec.rb
-  lib/phronomy/generator_verifier.rb
+  lib/phronomy/generation/generator_verifier.rb
   spec/phronomy/generator_verifier_spec.rb
   spec/integration/subgraph_parallel_agent_tool_spec.rb
   spec/phronomy/guarantee_model_spec.rb
@@ -197,11 +197,11 @@ syntax_files=(
   spec/phronomy/fault_injection_advanced_spec.rb
   spec/phronomy/persistence_architecture_regression_spec.rb
   lib/phronomy/agent/base.rb
-  lib/phronomy/agent_already_exists_error.rb
-  lib/phronomy/agent_purged_error.rb
+  lib/phronomy/agent/lifecycle_contract/agent_already_exists_error.rb
+  lib/phronomy/agent/lifecycle_contract/agent_purged_error.rb
   lib/phronomy/engine/runtime/agent_ownership_registry.rb
   lib/phronomy/agent/agent_root.rb
-  lib/phronomy/agent/llm_input_build_context.rb
+  lib/phronomy/agent/context_contract/llm_input_build_context.rb
   lib/phronomy/agent/shared_state.rb
   lib/phronomy/agent/concerns/before_llm_input.rb
   lib/phronomy/testing/persistence_contract/an_agent_repository.rb
@@ -322,7 +322,7 @@ bundle exec rspec \
   spec/integration/multi_agent_handoff_followup_spec.rb
 
 echo "== ACS-06 / CG-07 durable format / record-oriented Persistence SPI =="
-ruby -c lib/phronomy/persistence.rb >/dev/null
+ruby -c lib/phronomy/persistence/api/persistence.rb >/dev/null
 ruby -c lib/phronomy/persistence/durable_record.rb >/dev/null
 ruby -c lib/phronomy/persistence/durable_codec.rb >/dev/null
 ruby -c lib/phronomy/persistence/repository_facades.rb >/dev/null
@@ -467,7 +467,7 @@ for rel in [
     if fsm_new_has_id_kwarg(text):
         raise SystemExit(f"FAIL: {rel} still injects a domain/context ID as FSMSession id")
 
-workflow = pathlib.Path("lib/phronomy/workflow_runner.rb").read_text()
+workflow = pathlib.Path("lib/phronomy/workflow/execution/workflow_runner.rb").read_text()
 event_loop = pathlib.Path("lib/phronomy/engine/event_loop.rb").read_text()
 fsm = pathlib.Path("lib/phronomy/engine/fsm_session.rb").read_text()
 
@@ -487,7 +487,7 @@ for required in ["workflow_terminal_persistence_result", ":persisting_terminal",
 PY
 
 echo "== ACS-13 Workflow admission / durable terminal barrier =="
-ruby -c lib/phronomy/workflow_runner.rb >/dev/null
+ruby -c lib/phronomy/workflow/execution/workflow_runner.rb >/dev/null
 ruby -c lib/phronomy/engine/event_loop.rb >/dev/null
 ruby -c lib/phronomy/engine/fsm_session.rb >/dev/null
 ruby -c spec/phronomy/workflow/admission_spec.rb >/dev/null

data/benchmark/bench_agent_invoke.rb

@@ -5,11 +5,12 @@
 # Measures the per-invoke cost of the Phronomy::Agent::Base framework path
 # (context assembly, filter checks, before_llm_input hooks, response handling)
 # with a fully stubbed LLM. No network calls are made.
+# Each sample invokes a fresh Agent once. Agent construction is outside the
+# measured block; growing conversation history is a different workload.
 #
 # Scenarios:
 #   1. Minimal agent (no tools, no persistent Knowledge) — baseline framework overhead.
 #   2. Tool-aware agent with a registered stub Tool.
-#   3. Agent#stream setup latency (first-chunk time with stubbed stream).
 
 require "benchmark"
 require_relative "../lib/phronomy"
@@ -18,44 +19,21 @@ require_relative "../lib/phronomy"
 # Shared stubs
 # ---------------------------------------------------------------------------
 
-BenchAgentMessage = Struct.new(:role, :content, :tool_calls, :tokens) do
-  def self.assistant(content = "done")
-    new(:assistant, content, nil,
-      Struct.new(:input, :output, :cached, :cache_creation).new(5, 5, 0, 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(_) = self
-  def with_tool(_) = self
-  def with_temperature(_) = self
-  def with_cache_instructions(_) = self
-  def with_output_schema(_) = self
-  def on_tool_call(&) = self
-  def before_tool_call(&) = self
-  def last_message = @response
-
-  def ask(_)
-    @messages << @response
-    @response
-  end
+  protected
 
-  def stream(*)
-    yield @response.content if block_given?
+  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"
 
@@ -68,40 +46,41 @@ end
 # Agent classes
 # ---------------------------------------------------------------------------
 
-BENCH_RESP = BenchAgentMessage.assistant("benchmark complete")
-BENCH_RESP_CHAT = BenchStubChat.new(BENCH_RESP)
+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
 
-BENCH_AGENT_MINIMAL = bench_minimal_class.new
-BENCH_AGENT_TOOLS = bench_tool_class.new
-
 AGENT_INVOKE_ITERATIONS = 200
 
-puts "=== bench_agent_invoke ==="
-Benchmark.bm(50) do |x|
-  x.report("Agent#invoke — minimal (no tools), #{AGENT_INVOKE_ITERATIONS} iters") do
-    AGENT_INVOKE_ITERATIONS.times do
-      BENCH_AGENT_MINIMAL.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 — tool-aware, #{AGENT_INVOKE_ITERATIONS} iters") do
-    AGENT_INVOKE_ITERATIONS.times do
-      BENCH_AGENT_TOOLS.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,24 +38,23 @@ 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,
       token_budget: Phronomy::LlmContextWindow::TokenBudget.new(
-        context_window: [item_count * 16, 4_096].max,
-        max_output_tokens: 512
+        max_input_tokens: [item_count * 16, 4_096].max
       ),
       model_config: {}, previous_manifest: nil, metadata: {}
     )
   end
 
   def assembler_fixture
-    persistence = Phronomy::Persistence::InMemory.new
+    persistence = Phronomy::PersistenceComposition.in_memory.agent
     agent_class = Class.new(Phronomy::Agent::Base) do
       agent_definition id: "bench-manifest-context-assembler", version: 1
-      model "local-model"
-      context_window 16_384
+      # Resolve capabilities from RubyLLM's bundled registry; no provider call.
+      model "gpt-4o-mini"
       max_output_tokens 1_024
       instructions "Benchmark instruction"
     end
@@ -87,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
@@ -98,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
@@ -111,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"