phronomy 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd6beeb52633381ff9e249ec18a1dc422234c78e44f479e3549cd3c54591ab04
-  data.tar.gz: 6528144759933b359d2303b1499b678cbd4eb0c747ca9966f0c6542effb28196
+  metadata.gz: '095ac1376e77f34201dceeafec7dc114340aa2cae7cd8f1bb2bb7c2552e64e87'
+  data.tar.gz: 4d900c3bdc20e3fb0210046daffc4d78d1b990f118281c04037cc45beca2d699
 SHA512:
-  metadata.gz: 307b601d09f6113282eef52f3e547d259e728adf0ba9ac481e3d84dc99583b8510ad779c71e0abee8c78f180b3786d6eacb3fea66723432d93f523e7f4be756a
-  data.tar.gz: 6aed95a5486eaaa792e25ad4d058ebc804278dfa2bf648f216d120256154f7f1cccba86c056ec5176f98556f16e7b835c7102dd0129da5474f9ce93f221cbae8
+  metadata.gz: 3108c48424885f72ea256e6c7cd7dfa8a7230647727f288f9fce840ee9309a51b523e64748663a7d1341e88b0c05cfe5432cb91a521039b16f28b0e2c14a4714
+  data.tar.gz: 51795e8c019cb92d8a17eadb864b726f9359ed1c963b06acfb52cb7440b99234755ad2c7e169a5afb8e5958ea45b99635d9035eea4d3c4ceb84ac4d554fdc814

data/CHANGELOG.md

@@ -14,6 +14,46 @@ 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

data/README.md

@@ -45,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.
 

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/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).

data/docs/architecture/agent-configuration-and-tool-binding.md

@@ -0,0 +1,139 @@
+# Agent configuration and Tool binding (R09, first slice)
+
+## Role and boundary
+
+Agent::Base is the public declaration and lifecycle facade. Before tools are
+advertised to an LLM or installed in a runtime chat, its prepare_tool_class hook
+selects the Agent's alias and result filters for the original Tool class.
+ToolDefinitionSet and runtime projection installation use that same hook.
+MultiAgent::Orchestrator overrides it, calls super, then adds subagent context.
+
+Previously the hook also generated both decorator subclasses and bridged custom
+asynchronous results, including cancellation and physical completion. Refactor 42
+extracts that mechanism into Agent::ToolBinding in agent/tool_execution. Base
+retains the selection hook and its invocation keyword for Orchestrator cooperation.
+ToolBinding takes an explicit Tool class, alias and filter list; it holds no Agent
+reference and does not call private Agent methods back through send.
+
+| Owner | Responsibility |
+|---|---|
+| Base / Filterable | Select the original class's alias and ordered class, instance and scoped filters. |
+| ToolBinding | Construct alias/result-filter decorators, preserve effective Tool names, and bridge custom async results. |
+| Capability::Base / ToolExecutor | Default Tool call protocol and physical execution. |
+| ToolInvocation | Validation, authorization, execution supervision and state restoration. |
+| Orchestrator | Capture subagent parent/config/knowledge context after Base preparation. |
+
+There is one new internal class and one production file. ToolBinding is marked
+@api private, like other Agent implementation collaborators; it is not a new
+supported application API. No loader change, mixin, alias or public signature
+change is introduced. Definitions, approval, durable schemas and stored Tool
+state are unchanged.
+
+## Preparation and reading order
+
+Base first returns non-Class values unchanged. For classes it constructs the
+alias binding, then resolves filters, then prepares the filtered class. This
+order preserves subclass creation before filter selection. With neither alias
+nor filters the exact original class is returned. With an alias and no filters,
+the alias subclass is returned without instantiating a Tool.
+
+ToolBinding#prepare reads the effective name and the call_async method owner,
+then defines the synchronous decorator and, only when needed, the custom async
+decorator. filter_async_result registers physical and logical completion in that
+order. propagate_failure and complete_filtered_result separate terminal outcomes.
+The methods express one level below their operation names rather than leaving
+the whole callback protocol inside Base.
+
+The original Tool class remains the scoped-filter key even when an alias creates
+a subclass. Each preparation captures a newly collected filter list; it does not
+cache generated classes or deep-copy filter objects. Later registrations affect
+later preparations. The synchronous call passes the original args/keyword values
+to super and applies class, instance and scoped filters in that order, with the
+effective name and original args. Filter exceptions propagate without ToolError
+wrapping by this decorator.
+
+## Asynchronous contract retained
+
+- If call_async is owned by Capability::Base, leave it inherited: its ordinary
+  execution path reaches the decorated call. A second async filter wrapper would
+  apply the same filters twice.
+- Any other method owner, including an inherited custom implementation, receives
+  the custom async decorator. It forwards args/kwargs to super and wraps the
+  returned operation in PhysicalCompletionTask. It does not wait for completion.
+- Preserve logical completed/failed/cancelled status, values and error identity.
+  Failure skips filters. A filter StandardError fails the derived result with
+  that same exception. A synchronous startup exception still escapes call_async.
+- With on_physical_complete support, forward that signal independently of the
+  logical result. Logical cancellation/failure must not fabricate physical
+  completion while the source is still working. Physical completion can precede
+  the logical callback or already be true when the listener is registered.
+- Without that signal, mark physical completion before settling the derived
+  result, including filter failure. Listener registration remains physical first,
+  logical second, so already-settled operations are handled by existing callbacks.
+- Cancelling the derived result does not cancel the source. A later successful
+  source completion can still execute result filters, while its derived status
+  remains cancelled. This is existing behavior, not a new cancellation guarantee.
+
+No retry, additional cancellation propagation, thread/pool policy or physical
+completion guarantee is added. The source signal still describes source work,
+not a new synchronization boundary around the filter callback itself.
+
+## Agent declaration inheritance as currently implemented
+
+Do not infer one uniform inheritance rule from the word "configuration". The
+following describes current compatibility behavior; Refactor 42 does not change
+the DSL methods. Parent reads are live lookups, not snapshots taken at subclass
+creation.
+
+| Declaration / getter | Child without an own value | Own value / special behavior |
+|---|---|---|
+| model | Global configuration.default_model; does not read parent's model | Truthy setter, nil/false are reads. Global changes remain visible until an own value is set. |
+| instructions | Parent instructions, including the same Proc or template object | Text or block replaces the own value. nil without a block is a read, not a clear. |
+| provider | Parent provider | Truthy setter; nil/false read. |
+| tools | Parent tools array by reference | A Hash replaces the own class list. An empty Hash is an explicit empty list. nil reads. |
+| tool_aliases | Parent aliases merged with own aliases | Alias values are stringified; nil entries are omitted. A child nil alias or empty tools list does not erase inherited aliases. |
+| context_policy | Parent policy object, ultimately ContextPolicies::Default.instance | Exactly one ContextPolicy object replaces it. nil is invalid, not reset. |
+| temperature | nil; does not inherit | Truthy setter; zero is accepted; nil/false read. |
+| max_iterations | 10; does not inherit | Truthy setter; zero is accepted. |
+| cache_instructions | nil; does not inherit | nil reads, false is an explicit value. |
+| max_output_tokens | nil; does not inherit | nil reads; positive Integer conversion. context_window moved to the RubyLLM registry in Refactor 45. |
+| agent_definition | Raises until that class declares identity/revision | Each subclass requires its own definition; this is not inherited model configuration. |
+| input/output/tool_result_filter registries | Empty class registry; do not inherit | Registrations append on that class. Instance filters are separate. |
+| before_llm_input / _before_llm_input | nil class callback; does not inherit | Instance and global hook behavior remains separate. |
+
+The generic Agent rule does not override specialised subclass DSL such as
+Orchestrator's subagent registry. Tool/Capability declaration inheritance is also
+a different contract, already covered by its configuration-inheritance tests.
+
+The existing test description that said "normal class configuration still
+inherits" referred only to instructions and was too broad. It now names the
+actual checked rule. No new policy is inferred from that earlier wording.
+
+For compatibility, retain these rules in this source refactor. Uniform parent
+fallback, alias removal and copying inherited mutable values would be separate
+behavior changes requiring an explicit migration decision. They can change
+model/provider combinations, budgets, Tool names and application callbacks.
+
+## Verification and remaining R09 work
+
+Thirty-five new contract examples run against both the unchanged Refactor 41 and
+the candidate. They exercise selection/alias order, names, filter ordering,
+forwarded object identity, default/custom async behavior, logical/physical
+completion, cancellation and DSL inheritance. Existing Tool definition, approval,
+Orchestrator and full integration suites cover the cooperation paths.
+The release, API/SPI, RBS, style, isolated gem and examples gates are recorded in
+the distribution. Candidate remote CI, live PostgreSQL, live LLM and performance
+are not measured by this change.
+
+Refactor 42 is applied and independently verified at core 4a57a3c2. This
+completes the Tool binding and declaration-contract slice. Refactor 43 addresses
+the original Chat construction and explicit state-mutation scope; see the
+[Chat/state design](agent-chat-and-state-ownership.md). It preserves the Base
+hooks and operation/publication order rather than changing DSL semantics.
+
+Refactor 43 application was verified at core 5c4c0392; R09 is closed.
+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).
+
+Refactor 45 changes the token declarations as described in [the migration](rubyllm-2-token-ownership.md). Other Agent inheritance rules above remain unchanged. Tool schema/provider configuration follows the RubyLLM 2 inherited configuration contract.

data/docs/architecture/agent-context.md

@@ -84,8 +84,10 @@ See [Context Management](context-management.md) and
 ## 3. Live mutable ownership
 
 Within one Runtime/process, one mutable live Agent instance owns one `agent_id`.
-Loading or creating a second mutable live instance for the same `agent_id` is
-rejected.
+`Agent::OwnershipRegistry` reserves that identity before materialization;
+Runtime strongly retains the registry through the generic shutdown contract.
+Repeated load returns the same live instance, while duplicate create is rejected.
+See [ADR-041](../decisions/041-feature-owned-identity-registries.md).
 
 During active execution, EventLoop is the single writer of Phronomy-managed live
 Agent execution state. Blocking Persistence work and other synchronous work that