phronomy 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 636ce578204172927316a89f0f65a2bdfda49140822da98cd1eec9230d821105
-  data.tar.gz: 8d776e0ab9bf2775af4e23f77b0b29968a3d4962f8fbd877d3fe9574a3efb306
+  metadata.gz: '095ac1376e77f34201dceeafec7dc114340aa2cae7cd8f1bb2bb7c2552e64e87'
+  data.tar.gz: 4d900c3bdc20e3fb0210046daffc4d78d1b990f118281c04037cc45beca2d699
 SHA512:
-  metadata.gz: 81a2b295d5fb03d4cd03c6f3ceabca7b62f4e635fc5dd6ed3db31b1c5f59c6031fc38958895a1fc7b8e9fc75394a81181d51529ebb86f310e85cd2300a9395af
-  data.tar.gz: f701f8fd0be60d655e9676c8cbdfec93606cca20769da90b7c67617c9d876cbde51bf18a42531b7cf70079aa12863af022acd21500fe40cff64c04d5a70df6ab
+  metadata.gz: 3108c48424885f72ea256e6c7cd7dfa8a7230647727f288f9fce840ee9309a51b523e64748663a7d1341e88b0c05cfe5432cb91a521039b16f28b0e2c14a4714
+  data.tar.gz: 51795e8c019cb92d8a17eadb864b726f9359ed1c963b06acfb52cb7440b99234755ad2c7e169a5afb8e5958ea45b99635d9035eea4d3c4ceb84ac4d554fdc814

data/CHANGELOG.md

@@ -14,6 +14,77 @@ Release history for 0.14.0 and earlier is archived in
 
 ---
 
+## [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
+
+### Changed
+
+- Rename the public completion type to `Phronomy::TaskResult`; remove `Task`
+  without a compatibility alias in this development release.
+- Remove `Orchestrator#fan_out` and `#fan_out_async`. Use `dispatch_parallel`
+  for Agent-specific construction/knowledge/concurrency policy, or Execution
+  for application-defined JOB composition.
+- Preserve cancelled states and original cancellation errors across result
+  transformations, independently of failures that carry CancellationError.
+
+### Added
+
+- `TaskResult#flat_map`, `.all_settled`, and immutable input-order Outcome records.
+- `Execution.run_async` / `.run` for shared runtime fan-out/fan-in, explicit
+  invocation context, whole-execution timeout/cancellation and partial snapshots.
+- `Execution#observe` for scoped continuations of externally owned results.
+- Optional `invocation_context:` on `Blocking.call_async`, with one-way combined
+  context and individual controls shared with Agent admission.
+
+### Fixed
+
+- Dispose finished execution subscriptions and timers while retaining required
+  physical completion tracking. Orchestrator reuses the common Execution engine.
+
+See [Result composition and Execution](docs/async-composition.md) for migration,
+completion boundaries, cancellation and application responsibilities.
+
+---
+
 ## [0.25.0] - 2026-09-12
 
 ### Added

data/CONTRIBUTING.md

@@ -98,16 +98,16 @@ Do not change Ruby visibility merely to make it match an `@api` annotation.
 
 ### Async completion boundary
 
-`Phronomy::Task` is the caller-facing completion handle. EventLoop/FSMSession and
+`Phronomy::TaskResult` is the caller-facing completion handle. EventLoop/FSMSession and
 OffloadPool are execution/continuation mechanisms, not competing completion
 abstractions.
 
 Synchronous work that requires execution away from EventLoop must use an
 OffloadPool. Do not create production worker Threads in adapters, backends, or
 Tools to emulate asynchronous behavior. Logical waits between Phronomy
-lifecycles stay on EventLoop/FSMSession and settle a Task later.
+lifecycles stay on EventLoop/FSMSession and settle a TaskResult later.
 
-The framework owns Task settlement (`complete`, `fail`, and framework-driven
+The framework owns TaskResult settlement (`complete`, `fail`, and framework-driven
 cancellation). Application code should observe Tasks through `wait_result`,
 `on_complete`, `map`, and settlement state. Operation-wide cancellation of
 OffloadPool work is supplied through `CancellationToken`.
@@ -149,7 +149,7 @@ ambiguous. Do not renumber historical ADRs to repair that legacy collision.
 
 For Agent Context work, ADR-012 and ADR-013 define the current Journal,
 Manifest, Context Policy and persistent Knowledge model. ADR-010 defines the
-EventLoop/FSMSession, Task, and OffloadPool execution boundary. ADR-015 defines
+EventLoop/FSMSession, TaskResult, and OffloadPool execution boundary. ADR-015 defines
 the Tool public façade, extension-SPI boundary, and RBS ownership rules.
 
 Current explanatory architecture starts at [`docs/architecture.md`](docs/architecture.md).

data/README.md

@@ -22,8 +22,10 @@ tracking `main` directly.
 - **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.
 - **EventLoop + FSMSession** — the framework control plane for logical lifecycle coordination.
 - **OffloadPool** — bounded operating-system-thread execution boundary for synchronous work that must not run on EventLoop.
-- **Task** — the common thread-free completion handle returned by Phronomy asynchronous APIs, including OffloadPool-backed work.
-- **Task.completed / Task.failed** — already-settled application results without starting execution.
+- **TaskResult** — the common thread-free completion handle returned by Phronomy asynchronous APIs, including OffloadPool-backed work.
+- **TaskResult.completed / TaskResult.failed** — already-settled application results without starting execution.
+- **TaskResult.map / flat_map / all_settled** — result transformation, asynchronous chaining and ordered all-settled observation.
+- **Execution.run_async / run** — start application JOBs and join their final results under a whole-execution timeout and cancellation scope.
 - **Blocking.call_async** — submits synchronous application work to the existing bounded OffloadPool without waiting for queue space.
 - **Journal / Context Policy / Manifest** — canonical history plus per-LLM-call context selection.
 
@@ -43,6 +45,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.
 
@@ -86,8 +92,8 @@ class. The legacy `Phronomy::Agent::Context::Capability::Base` constant remains
 valid for compatibility.
 
 For non-blocking top-level use, call `invoke_async` and keep the returned
-`Phronomy::Task`. Inside Phronomy lifecycle callbacks, do not block waiting for
-another Task; continue through explicit events instead.
+`Phronomy::TaskResult`. Inside Phronomy lifecycle callbacks, do not block waiting for
+another TaskResult; continue through explicit events instead.
 
 ```ruby
 task = ResearchAgent.new.invoke_async("Research Ruby AI frameworks")
@@ -128,14 +134,14 @@ Runtime
 └─ EventLoop-driven timers
 
 EventLoop / FSMSession ─┐
-                       ├─> Task = completion handle
+                       ├─> TaskResult = completion handle
 OffloadPool ────────────┘
 ```
 
 Logical waiting remains in EventLoop/FSMSession state. Synchronous work that
 would block EventLoop uses the bounded OffloadPool. OffloadPool-specific queue,
 worker, timeout, and abandonment state remains private runtime machinery; callers
-observe completion through `Phronomy::Task`. See
+observe completion through `Phronomy::TaskResult`. See
 [Runtime and concurrency](docs/runtime-and-concurrency.md) for the detailed
 contracts, timeout/cancellation semantics, metrics, and callback rules.
 
@@ -144,7 +150,8 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 - [Getting started](docs/getting-started.md) — installation, RubyLLM setup, Agent/Workflow basics, persistence, streaming.
 - [Features and API stability](docs/features.md) — public feature matrix and stability labels.
 - [Architecture](docs/architecture.md) — canonical current explanatory architecture entry and authority navigation.
-- [Runtime and concurrency](docs/runtime-and-concurrency.md) — EventLoop, FSMSession, Task, OffloadPool, cancellation, observability.
+- [Runtime and concurrency](docs/runtime-and-concurrency.md) — EventLoop, FSMSession, TaskResult, OffloadPool, cancellation, observability.
+- [Result composition and Execution](docs/async-composition.md) — application JOBs, map/flat_map, fan-in snapshots, context ownership and migration.
 - [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).

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,10 +19,12 @@ require_relative "../lib/phronomy"
 # Shared stubs
 # ---------------------------------------------------------------------------
 
-BenchAgentMessage = Struct.new(:role, :content, :tool_calls, :tokens) do
+module BenchAgentMessage
   def self.assistant(content = "done")
-    new(:assistant, content, nil,
-      Struct.new(:input, :output, :cached, :cache_creation).new(5, 5, 0, 0))
+    RubyLLM::Message.new(
+      role: :assistant, content: content,
+      tokens: RubyLLM::Tokens.new(input: 5, output: 5, cache_read: 0, cache_write: 0)
+    )
   end
 end
 
@@ -34,22 +37,25 @@ class BenchStubChat
     @messages = []
   end
 
-  def with_instructions(_) = self
-  def with_tool(_) = self
+  def with_instructions(_, **_options) = self
+  def with_tools(*) = 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 after_message(&block)
+    @after_message = block
+    self
+  end
+
   def ask(_)
-    @messages << @response
-    @response
+    complete
   end
 
-  def stream(*)
-    yield @response.content if block_given?
+  def complete
+    @messages << @response
+    @after_message&.call(@response)
     @response
   end
 end
@@ -69,7 +75,6 @@ end
 # ---------------------------------------------------------------------------
 
 BENCH_RESP = BenchAgentMessage.assistant("benchmark complete")
-BENCH_RESP_CHAT = BenchStubChat.new(BENCH_RESP)
 
 bench_minimal_class = Class.new(Phronomy::Agent::Base) do
   agent_definition id: "bench-minimal", version: 1
@@ -86,22 +91,21 @@ bench_tool_class = Class.new(Phronomy::Agent::Base) do
   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
+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 — minimal (no tools), #{AGENT_INVOKE_ITERATIONS} iters") do
-    AGENT_INVOKE_ITERATIONS.times do
-      BENCH_AGENT_MINIMAL.invoke("ping")
+  x.report("Agent#invoke — fresh, no tools, #{AGENT_INVOKE_ITERATIONS} iters") do
+    BENCH_AGENTS_MINIMAL.each do |agent|
+      agent.invoke("ping")
     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

data/benchmark/bench_context_assembler.rb

@@ -43,19 +43,18 @@ module BenchContextAssembler
       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::Persistence.in_memory
     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

data/benchmark/bench_regression.rb

@@ -102,7 +102,7 @@ stub_agent_class = Class.new(Phronomy::Agent::Base) do
   end
 
   define_method(:invoke_async) do |input, **_kw|
-    task = Phronomy::Task.deferred(name: "bench-stub")
+    task = Phronomy::TaskResult.deferred(name: "bench-stub")
     begin
       task.complete(invoke(input))
     rescue => error

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

@@ -0,0 +1,147 @@
+# Agent Chat and explicit state ownership (R09, second slice)
+
+## Purpose and clients
+
+Agent::Base is the declaration and lifecycle facade used by application Agent
+subclasses. It also supplies internal hooks to normal execution, follow-up LLM
+calls and recovery. Those callers need a Chat built from the selected or saved
+model settings and populated with an already materialized projection. They do
+not ask the Chat constructor to make Context Policy decisions again.
+
+Applications create Agents and explicitly add knowledge, clear context/history,
+reset context or close an idle Agent through Base. These operations append
+Journal records and advance an AgentRoot together. The existing live root is
+authoritative; an operation must not silently reload a newer root and retry.
+
+Refactor 42 extracted ToolBinding and documented existing declaration rules.
+Refactor 43 separates the remaining Chat construction and explicit state writes
+while keeping the Base facade and live-state publication boundary.
+
+## Ownership and placement
+
+| Owner | Responsibility |
+|---|---|
+| Base | Public declarations and lifecycle entry points, live-owner checks, selected class settings, operation-specific root changes, projection installation and publication of successful state writes. |
+| RuntimeChatBuilder | RubyLLM Chat options and setters; provider-specific instruction cache representation. |
+| StateWriter | Initial root/context/knowledge persistence and explicit idle-Agent Journal/root changes in one transaction. |
+| ContextImporter / JournalRecord / AgentRoot | Existing history validation, record meanings and immutable root values. |
+| ToolBinding / Orchestrator | Existing Tool decoration and invocation-specific subagent context. |
+| ExecutionCoordinator and its workers | Existing execution-time writes and EventLoop-side publication, unchanged here. |
+
+RuntimeChatBuilder and StateWriter live in agent/context_assembly, whose existing
+collaborators already turn context inputs into runtime or durable records.
+StateWriter is orchestration over ContextImporter, JournalRecord and AgentRoot;
+it is not a low-level lifecycle primitive or a raw storage adapter. Placing it
+in lifecycle would introduce lifecycle -> context_assembly and enlarge the
+existing directory cycle. That placement was rejected during design validation.
+No new directory, loader rule, mixin or namespace alias is needed.
+
+There are two new internal collaborator classes, plus StateWriter's private
+Update data value containing root and appended records. Neither collaborator
+holds an Agent reference or invokes private Agent methods through send. The
+mutation block passed to StateWriter is the existing operation-specific root
+proposal, called at the same point inside the transaction.
+
+## Chat construction and installation
+
+Base#build_chat selects its default model/provider/temperature/token settings
+only when model_config is falsey. An explicit empty Hash remains an explicit
+config. RuntimeChatBuilder then builds options, creates RubyLLM.chat, applies
+temperature, optionally applies max_output_tokens and returns the original
+Chat, irrespective of setter return values. Zero remains a valid setting.
+
+Base#apply_instructions keeps its signature and delegates the provider detail.
+Only a truthy cache flag with provider.to_s == "anthropic" wraps instructions
+in Anthropic::Content(cache: true). All other values pass through unchanged;
+the with_instructions return value is retained.
+
+Base#_apply_runtime_projection_to_chat remains a short orchestration hook. It
+installs system instructions, prepares and installs each Tool in order, then
+appends the original message objects to the existing Chat messages. Keeping the
+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.
+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,
+provider-independent SPI, LLM call or Tool execution path is introduced.
+
+## Initial persistence
+
+Base resolves the Agent definition before calling StateWriter#create_root.
+StateWriter constructs the initial root, then performs the existing sequence:
+
+1. Create the root in the transaction.
+2. Import/encode context records, followed by knowledge records, in order.
+3. If records exist, append them at position zero, advance both revisions to
+   one and save the root with expected_revision zero.
+4. Return the resulting root after the transaction call returns successfully.
+
+Empty initial input does not append or advance revisions. String coercion of
+knowledge, metadata normalization, imported text/JSON handling and invalid-format
+errors remain unchanged. Base's initialize_owned_state still assigns the root,
+reads the committed Journal and freezes its local record array. Hydration and
+definition compatibility checks remain unchanged in Base.
+
+## Explicit mutation and publication
+
+For add_knowledge and context/lifecycle changes, Base first checks live ownership
+and captures agent_root. StateWriter takes that root, persistence and agent ID
+explicitly. Each operation retains this transaction sequence:
+
+1. Assert durable execution idleness.
+2. Construct the content/state record and append with the captured Journal head.
+3. Build the next root; a context mutation's proposal block runs after append.
+4. Save with the captured expected Agent revision.
+5. After the transaction call returns, return Update(root, appended records).
+
+Base applies the returned Journal records before replacing @root. StateWriter
+never publishes live state and never reloads the mutable root or Journal.
+add_knowledge still returns self; clear/reset/close still return the new root.
+close! increments Agent revision while preserving context revision. Context
+changes preserve the old generation in the event and the existing revision
+fallback rule in the resulting root.
+
+Block, content, append, CAS and commit failures escape without publication.
+Failures inside a supported transaction roll back its durable writes. An error
+is not wrapped, retried or turned into a false successful return. The transaction
+method's own return value is ignored as before.
+
+This is not a stronger transaction or concurrency contract. If a backend commits
+then reports an unknown outcome, or local Journal publication fails after a
+successful commit, durable and live state can differ just as before. There is
+no new F1 reconciliation for these manual operations. If an application encloses
+an Agent mutation in an outer Persistence transaction, returning from the inner
+scope is not proof of the outer commit; this refactor adds no deferred-publication
+or outer-rollback coordination. Application-owned outer transactions need a
+separate design decision, not an implicit guarantee from this extraction.
+
+The public lifecycle checks, purge ownership protocol, admission, hydration,
+execution commits, SQL and stored formats are unchanged. Relocated private
+record-building helpers are not retained as an extension API. Retained Chat,
+Tool and root-proposal hooks keep their names and signatures.
+
+## Validation and completion rule
+
+Thirty-seven additional behavioral examples run through Base against both the
+unchanged Refactor 42 and this candidate. They cover saved/default/empty config,
+provider options, setter and hook ordering, original objects/errors, import
+formats, atomic rollback, idle checks, event/revision rules and publication.
+The existing architecture guard now checks StateWriter as well as Base for
+forbidden mutable-root/Journal reload and live-state publication paths.
+
+Full core/integration/examples, real SQLite, public API/SPI, RBS, style, isolated
+gem loading and independent package application are recorded in the release
+evidence. New private helpers are distinguished from the unchanged public
+contract and retained hook signatures. Static dependency analysis rejects new
+cycle membership rather than merely checking unchanged edge counts.
+
+Refactor 43 is applied and verified at core 5c4c0392; R09 is closed. Its Tool
+binding and declaration rules were already verified in Refactor 42. Base remains
+the public facade; keeping short orchestration methods there is intentional.
+The DSL behavior itself remains unchanged. R10 is implemented in Refactor 44,
+pending application verification. The published SVG is applied43-01. See the
+[naming boundary](entry-action-and-team-wording.md) and the separate
+[open Tool schema finding](tool-schema-recording-gap.md).