phronomy 0.28.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f097c81530a33bd631974866ff26a0d2ec8b4793286c6dfa0bb0facaac4fdd83
-  data.tar.gz: 80b9980737c80446f660d9a058aa1b898bdcdec452e517764261c386c32a1e78
+  metadata.gz: 46b13a1255f5821e321de0e3817f9fc2335ae2eba81dc7142a01295ffffcdd05
+  data.tar.gz: c268bfd441361880ce4c6c6a84f03e7e0530b5e1ca8736e87bfba78756a69c89
 SHA512:
-  metadata.gz: 2cacf04ecea168021b36835f12901723380a7a908d0173f23b564e9bb67d4f85cf46bf958949fd4257043393234ef5acc7e8d9cecdcf68beac61b0c7ce454084
-  data.tar.gz: c7f7b1d9cbcd54d0d0d9bb7583e5587ecadfafa987788f44e8c8abc0f9fa75241092d63a543669b55a6837fc1c2c09c102cf514578b6c266b2c85ff17d2ba2cc
+  metadata.gz: 9f53504e27f5cefedb2370ed495387c17cf98ae850b847497090b17fe1971545a565bfe4533368f47646c5953352aebc4f29801afdb3a2691a54927f60ec1df4
+  data.tar.gz: 4f9dace274b6a09ad4096569cd8a459dc74df63263c8d4fdc1455d6628e70c93464490a971c638a24aea844d09eb85f9f4ceafa64e9c9e39f5345daa6b83fffb

data/CHANGELOG.md

@@ -12,7 +12,102 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
-### r8 first implementation unit (breaking, unreleased)
+## [0.30.0] - 2026-10-24
+
+### Added
+
+- Agent `output_schema:` and `OutputParser::JsonSchemaParser` provide strict,
+  immutable JSON results. Refused, incomplete and invalid output raises
+  `Agent::OutputError`; native schema delivery is preserved through Tool rounds,
+  approval and recovery without output repair or replaying confirmed Tool work.
+- Explicit `LLMAdapter::LMStudio` selection identifies the known generated-format
+  rejection as `llm.provider_output_parse_failed`, retaining the actual HTTP
+  status and original SDK cause. Opt-in retry resends the same eligible,
+  non-streaming gpt-oss-20b request at most once, without replaying Agent,
+  Workflow or Tool work. Ordinary SDK retries are disabled in this backend's
+  private snapshot; the default backend and global SDK settings are unchanged.
+
+### Changed
+
+- GeneratorVerifier owns immutable evaluation Results, explicit approval routing
+  and Agent lifetime. Use `accepted?`, `termination_reason` and
+  `raise_if_unaccepted`; `output_failed` distinguishes invalid output from a
+  completed evaluation that reaches `iteration_limit`. Acceptance reports the
+  configured conditions, not the truth of generated content.
+- Agent scopes and GeneratorVerifier scopes await a directly returned TaskResult
+  before releasing their owned Agents. Cleanup preserves the primary failure,
+  successful value and handles needed to retry release.
+- Tracing usage is a plain token-count Hash. Custom tracer/exporter callers must
+  project LLM-domain TokenUsage values before crossing the tracing boundary.
+- Require Faraday 2.14.4 and faraday-net_http 3.4.4 as the tested HTTP support
+  floors. Concrete LLM/Embeddings adapters translate recognized network failures
+  into their public TransportError types while preserving causes and callback
+  exceptions; cancellation and unknown internal failures are not broadly mapped.
+  Strict JSON decoding requires JSON >= 2.21.2 and < 3.
+
+### Removed
+
+- GeneratorVerifier parser fallback/repair hooks, `trusted`/`trusted?`,
+  `raise_if_untrusted` and `LowConfidenceError`. Migrate saved Result data with
+  `scripts/migrate_generator_verifier_result.rb`; no compatibility aliases are
+  provided. See the [Result and lifetime contract](docs/architecture/generator-verifier-lifecycle-result.md).
+
+### Fixed
+
+- Preserve each SharedState member's explicitly configured model when creating
+  its internal instrumented Agent. Keep ordinary Agent inheritance and the
+  global fallback for members without an explicit model unchanged.
+- Preserve canonical assistant-message metadata through Agent Tool rounds,
+  imports, persistence and recovery. The RubyLLM backend retains supported
+  thinking text/signatures and raw reasoning, including final streaming
+  responses, and delegates wire rendering to the existing SDK. Incompatible
+  continuation scope/version is rejected before inference; legacy messages
+  without this metadata remain usable. No database migration is required. See
+  [continuation compatibility](docs/architecture/llm-continuation-metadata.md).
+- Enforce `Agent.max_iterations = N` as at most N logical LLM calls per
+  execution, including the first and final response. Remove the premature FSM
+  cutoff that stopped the ninth single-Tool round before call ten. Tool count,
+  approval/resume, streaming chunks and SDK HTTP retries do not consume extra
+  logical calls; this limit does not bound physical HTTP attempts or Tool count.
+  Preserve the admitted limit and consumed-call records across approval,
+  recovery and a fresh Runtime/database pool. Legacy executions without the
+  saved limit use the current class setting. A final response on call N succeeds;
+  Tools requested on call N retain their results, and call N+1 raises the existing
+  `RecursionLimitError`. Zero permits no call; invalid limits fail before inference.
+  Generic Engine transition protection remains in place. This correction can
+  allow work previously stopped too early and stop runs previously able to reset
+  their budget on approval. Deploy at a quiescent Runtime boundary; see
+  [iteration budget migration](docs/architecture/agent-iteration-budget.md).
+
+### Verification and migration
+
+- Real LM Studio acceptance identified HTTP 400 PEG failures, performed one
+  identical-request retry, and returned the final error at the adapter's own
+  limit after the second failure. A separate application invocation succeeded
+  initially with HTTP 200: two application invocations, three generation POSTs.
+  This is not recovery by retry within one invocation. Recovery by retry,
+  recovery rate, the PEG root cause and recurrence resolution remain unverified.
+- Review the [structured-output migration](docs/architecture/structured-output-and-scope.md),
+  [continuation compatibility](docs/architecture/llm-continuation-metadata.md),
+  [iteration budget migration](docs/architecture/agent-iteration-budget.md) and
+  [LM Studio retry policy](docs/architecture/lm-studio-output-failures.md) before
+  upgrading persistent or in-flight applications.
+
+---
+
+## [0.29.0] - 2026-10-13
+
+See the [0.29.0 release record](https://github.com/Raizo-TCS/phronomy/releases/tag/v0.29.0).
+
+---
+
+## [0.28.0] - 2026-10-09
+
+The architecture notes below were already included in this release and carried
+unchanged in the 0.29.0 changelog. They are retained from the former Unreleased
+section and are not new 0.30.0 changes.
+
+### r8 first implementation unit (breaking)
 
 - Move Context policy/plan/manifest/budget/prompt operations into `Phronomy::Context`.
   Agent retains snapshot, journal and lifecycle ownership. Manifest and execution

data/README.md

@@ -4,6 +4,8 @@
 > This project is primarily developed and maintained by **AI coding agents**.
 > As a result, `main` receives frequent, large, and unannounced changes.
 > External contributors should expect significant churn and potential conflicts at any time.
+> Correct responsibility boundaries and behavior take priority over backward compatibility.
+> Obsolete APIs and compatibility-only paths are removed; update applications with the documented API changes.
 > We apologise for the instability this may cause.
 
 **Phronomy** is a Ruby AI agent framework for stateful Agents, Workflows, Tools,
@@ -21,7 +23,7 @@ tracking `main` directly.
 
 - **Agent** — stateful, persistence-backed LLM agent with canonical execution history.
 - **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.
+- **Workflow** — state-machine-driven application workflow with task states, 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.
 - **EventLoop + FSMSession** — the framework control plane for logical lifecycle coordination.
@@ -35,6 +37,22 @@ tracking `main` directly.
 
 See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
 
+The following application APIs are available as Beta in v0.30.0:
+
+| API | Stability | Contract |
+|---|---|---|
+| `Phronomy::LLMAdapter::LMStudio` | Beta | Explicit known-output-error identification and bounded opt-in retry; [policy and evidence limits](docs/architecture/lm-studio-output-failures.md) |
+| Agent `output_schema:`, `Agent::OutputError` and `OutputParser::JsonSchemaParser` | Beta | Agent returns validated immutable JSON or an explicit output failure; [contract and migration](docs/architecture/structured-output-and-scope.md) |
+| `Phronomy::GeneratorVerifier`, its approval/lifetime operations and immutable `Result` with output-failure diagnostics | Beta | [Generation and structured-output contract](docs/architecture/structured-output-and-scope.md) |
+| `Agent.open_scope`, `Agent::Scope`, `Agent::Base#unload_async / #unload!`, `AgentUnloadedError` and `Agent::ScopeCleanupError` | Beta | Runtime-bound ownership and safe release of idle Agent incarnations without changing saved history or closing the Store; [contract](docs/architecture/dx05-agent-scope.md) |
+| `Workflow::Builder#task_state` and `WorkflowTaskResumeError` | Beta | State-entry-scoped Task completion, live cancellation and explicit restart rejection; [contract](docs/architecture/dx05-workflow-task-state.md) |
+| `Phronomy::Integrations::OrderedEventDelivery` | Beta | Optional ordered delivery with bounded admission and explicit drain lifetime; [usage](docs/ordered-event-delivery.md) |
+| `Phronomy::Error#code` and error constructor `code:` | Beta | Optional reason codes and bounded causes retained in saved failure diagnostics; [meaning and compatibility](docs/architecture/error-api-review.md) |
+| `Phronomy::AgentNotFoundError#agent_id` | Beta | Identifies absence of the requested Agent root; referenced history and Content failures retain their own errors; [migration](docs/architecture/error-api-review.md) |
+| `Phronomy::MultiAgent::TeamNotFoundError` and `TeamBusyError`, with `team_id` | Beta | Team-owned absence and busy errors; child Agent failures retain their Agent classification; [migration](docs/architecture/error-api-review.md) |
+| `Phronomy::Embeddings::AuthenticationError` and `RateLimitError` | Beta | Embeddings-owned transport error subclasses retaining the provider cause; [migration](docs/architecture/error-api-review.md) |
+| `Phronomy::Tracing::Base.trace_with` | Beta | Uses the tracer start/finish SPI, attempts finish once, and preserves a primary application error; [contract](docs/architecture/error-api-review.md) |
+
 ## Installation
 
 Add Phronomy to your Gemfile:
@@ -49,12 +67,21 @@ Then run:
 bundle install
 ```
 
-This refactoring branch requires RubyLLM 2.0.x. See the
+Phronomy requires RubyLLM 2.0.x. The tested minimum HTTP stack is Faraday
+2.14.4 and faraday-net_http 3.4.4; newer versions within their respective major
+versions are allowed. Both floors are explicit: raising Faraday alone can still
+resolve an old Net::HTTP adapter that loses HTTP status during streaming.
+CI checks fresh resolution and this exact pair with MCP 1.0.0. These are verified
+support floors, not a claim about the first upstream release containing a fix.
+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.
+your application. The default adapter delegates transport retry and timeout policy
+to RubyLLM. The explicitly selected LMStudio backend instead disables SDK retries
+and can retry one narrowly recognized generated-format failure at most once;
+see its [policy](docs/architecture/lm-studio-output-failures.md).
 
 ```ruby
 RubyLLM.configure do |c|
@@ -91,9 +118,7 @@ result = ResearchAgent.new.invoke("What happened in AI research this week?")
 puts result[:output]
 ```
 
-`Phronomy::Tool::Base` is the public authoring name for the existing Tool base
-class. The legacy `Phronomy::Tool::Base` constant remains
-valid for compatibility.
+`Phronomy::Tool::Base` is the public base class for application-defined Tools.
 
 For non-blocking top-level use, call `invoke_async` and keep the returned
 `Phronomy::TaskResult`. Inside Phronomy lifecycle callbacks, do not block waiting for
@@ -152,6 +177,7 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 ## Documentation
 
 - [Getting started](docs/getting-started.md) — installation, RubyLLM setup, Agent/Workflow basics, persistence, streaming.
+- [Application recipes](docs/application-recipes.md) — complete persistence, streaming, and Workflow examples, including explicit failure handling.
 - [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, TaskResult, OffloadPool, cancellation, observability.

data/docs/application-recipes.md

@@ -0,0 +1,229 @@
+# Application recipes
+
+Start with [Getting started](getting-started.md). Every `ruby runnable` block
+below is a complete example after `require "phronomy"` and provider configuration.
+CI substitutes only the LLM adapter; Agent, Tool and Workflow operations are real.
+
+## Choose the completion channel
+
+| Need | Public API | Caller responsibility |
+|---|---|---|
+| One final answer | `agent.invoke(input)` | Call from an external thread |
+| Nonblocking final answer | `agent.invoke_async(input)` | Observe the returned TaskResult |
+| Intermediate events | Construction-time `on_event:` | Keep the callback short |
+| Streamed tokens | `stream` / `stream_async` with a listener | Move network delivery out of the callback |
+| Durable approval | `approve_async` with the request IDs | Apply the application's authorization decision |
+| State-owned asynchronous result | `task_state(name, start:, apply:)` | Framework correlates completion to state entry |
+| Live Workflow notification | `workflow.signal(...)` | Check admission; correlate the waiting operation |
+
+`TaskResult#wait_result` waits at an external application boundary. Completion
+callbacks and Agent listeners must not block EventLoop. A wait timeout does not
+cancel the underlying operation. The caller owns cancellation and cleanup.
+
+## Create, load and get
+
+```ruby runnable
+class ConversationAgent < Phronomy::Agent::Base
+  agent_definition id: "recipe-conversation", version: 1
+  model "gpt-4o-mini"
+  instructions "Answer briefly."
+end
+
+store = Phronomy::PersistenceComposition.in_memory.agent
+agent = ConversationAgent.create(agent_id: "recipe-session", persistence: store)
+puts agent.invoke("Hello").fetch(:output)
+
+# A live lookup is not a database read. Loading a live identity returns its owner.
+raise "Unexpected owner" unless ConversationAgent.get("recipe-session").equal?(agent)
+raise "Unexpected load" unless ConversationAgent.load("recipe-session", persistence: store).equal?(agent)
+
+def load_existing_agent(agent_class:, agent_id:, persistence:)
+  agent_class.load(agent_id, persistence: persistence)
+rescue Phronomy::AgentNotFoundError => error
+  raise unless error.agent_id == agent_id.to_s
+  nil
+end
+
+missing = load_existing_agent(
+  agent_class: ConversationAgent, agent_id: "missing-session", persistence: store
+)
+raise "Expected a missing Agent" unless missing.nil?
+```
+
+This application treats only absence as `nil`. Storage unavailability, state
+conflicts and recovery requirements remain errors. `create` is not upsert; do
+not catch every persistence failure and create a replacement conversation.
+The in-memory store is for this example; a durable backend must outlive Runtime
+to support process restart. See [persistence failures](migrations/persistence-failure-contracts.md).
+
+## Streaming and final results
+
+```ruby runnable
+class StreamingAgent < Phronomy::Agent::Base
+  agent_definition id: "recipe-streaming", version: 1
+  model "gpt-4o-mini"
+  instructions "Explain briefly."
+end
+
+events = Queue.new
+agent = StreamingAgent.new(on_event: ->(event) {
+  events << event if event.type == :token
+})
+
+task = agent.stream_async("Explain asynchronous results")
+result = task.wait_result
+puts result.fetch(:output)
+puts "Received #{events.size} token events"
+```
+
+The unbounded Queue is an in-process teaching example. A Web application needs
+bounded admission and ordered delivery outside the listener, such as Example 18.
+Register the listener at `new`/`create`/first `load`; per-invocation listener
+arguments or blocks are rejected. Do not replace a listener by loading an
+already-live Agent. See [approval](getting-started.md#human-in-the-loop-approval)
+for the separate durable approval identifiers and application decision.
+
+## Workflow task states
+
+When a Workflow owns the start of an operation, use `task_state` to keep the
+application focused on its operation, result fields and routing decisions.
+The example below returns the original error to its caller if either invocation
+fails; it does not silently retry or convert a failed invocation into an answer.
+
+```ruby runnable
+class TwoAnswersState
+  include Phronomy::WorkflowContext
+  field :question, type: :replace
+  field :answers, type: :replace, default: -> { [] }
+end
+class TwoAnswersAgent < Phronomy::Agent::Base
+  agent_definition id: "recipe-two-answers", version: 1
+  model "gpt-4o-mini"
+  instructions "Answer briefly."
+end
+agent = TwoAnswersAgent.new
+workflow = Phronomy::Workflow.define(TwoAnswersState) do
+  initial :asking
+  task_state :asking,
+    start: ->(state) { agent.invoke_async(state.question) },
+    apply: ->(state, result) { state.merge(answers: state.answers + [result.fetch(:output)]) }
+  state :decide
+  transition from: :asking, to: :decide
+  transition from: :decide, to: :__finish__, guard: ->(state) { state.answers.length >= 2 }
+  transition from: :decide, to: :asking
+end
+puts workflow.invoke({question: "Explain completion handles"}).answers
+```
+
+Expected business failures can be converted into application values before
+returning the source Task, for example using `TaskResult.all_settled` and `map`.
+Phronomy does not select a fallback or retry policy. See the
+[full contract](architecture/dx05-workflow-task-state.md).
+
+## Workflow completion and failures
+
+The following **legacy low-level signal recipe** is retained for existing users
+and its compatibility tests. New state-owned asynchronous operations should use
+`task_state` above. The restrictions below apply to this manual recipe, not to
+the new task-state API.
+
+This recipe targets **one live waiting stage**. Do not restart, reenter or replace
+that stage while a result is pending. A logical `workflow_instance_id` alone does
+not identify a particular execution or waiting operation. For those wider cases,
+application operation IDs and receiver-side guards are necessary.
+
+```ruby runnable
+def request_answer(agent:, workflow:, workflow_instance_id:, question:,
+  on_delivery_error:)
+  task = agent.invoke_async(question).map do |result|
+    {answer: result.fetch(:output)}
+  end
+
+  task.on_complete do |payload, operation_error|
+    delivery_error = nil
+    begin
+      accepted = workflow.signal(
+        workflow_instance_id: workflow_instance_id,
+        event: :answer_ready,
+        payload: operation_error ? {error: operation_error} : payload
+      )
+      unless accepted
+        delivery_error = Phronomy::Error.new("Workflow did not accept answer_ready")
+      end
+    rescue => error
+      delivery_error = error
+    end
+    on_delivery_error.call(delivery_error) if delivery_error
+  end
+
+  nil
+end
+
+class AnswerAgent < Phronomy::Agent::Base
+  agent_definition id: "recipe-answer", version: 1
+  model "gpt-4o-mini"
+  instructions "Answer briefly."
+end
+
+class AnswerState
+  include Phronomy::WorkflowContext
+  field :question, type: :replace
+  field :answer, type: :replace
+  field :error_message, type: :replace
+end
+
+agent = AnswerAgent.new
+delivery_errors = Queue.new
+workflow = nil
+workflow = Phronomy::Workflow.define(AnswerState) do
+  initial :asking
+  state :asking
+  state :done
+  entry :asking, ->(state) {
+    request_answer(
+      agent: agent, workflow: workflow,
+      workflow_instance_id: state.workflow_instance_id, question: state.question,
+      on_delivery_error: ->(error) { delivery_errors << error }
+    )
+    state
+  }
+  transition from: :asking, on: :answer_ready, to: :done,
+    action: ->(state, event) {
+      error = event.payload[:error]
+      error ? state.merge(error_message: error.message) : state.merge(answer: event.payload.fetch(:answer))
+    }
+  transition from: :done, to: :__finish__
+end
+
+final = workflow.invoke(
+  {question: "What is a completion handle?"},
+  config: {workflow_instance_id: "recipe-answer"}
+)
+puts final.error_message || final.answer
+raise delivery_errors.pop unless delivery_errors.empty?
+```
+
+The receiver handles both answer and error; changing only the sender would be
+incomplete. Store a serializable diagnostic, not the exception object, in the
+Workflow context. Result mapping failures (such as a missing `:output`) also
+become operation failures. Synchronous submission errors still propagate to
+the caller of `request_answer`.
+
+`signal == true` means admission, not transition completion or durable success.
+`false` and signal exceptions reach `on_delivery_error` once without automatic
+retry. This callback must be short and nonblocking. Its own exceptions follow
+TaskResult's existing callback logging policy; they do not change the settled
+operation result. Logging depends on the configured logger.
+
+Delivery rejection does not itself settle a waiting Workflow. The application
+must observe its diagnostic channel and decide whether to cancel or recover.
+The synchronous invocation above illustrates successful delivery. Production
+callers needing a wait limit should use `invoke_async` and manage both the
+Workflow TaskResult and the diagnostic channel at their external boundary.
+
+No generic Workflow forwarding helper is required by these recipes. A helper
+must first establish how an old result is prevented from reaching a new waiting
+stage; internal execution generations or automatic recovery are not implied.
+
+For an application-local extraction with the same limited lifetime, see the
+[bounded completion recipe](workflow-completion.md). It is not a new library API.

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

@@ -137,3 +137,11 @@ The published SVG is applied43-01. See the [naming boundary](entry-action-and-te
 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.
+
+## Agent iteration budget correction
+
+`Agent.max_iterations` now bounds logical LLM calls per Agent execution, including
+its first call and its final response. The nonnegative Integer limit is captured
+at admission; zero permits no call. Tool count, approval/resume and backend HTTP
+retries do not consume additional iterations. Declaration inheritance is unchanged.
+See [the iteration-budget boundary and migration](agent-iteration-budget.md).

data/docs/architecture/agent-iteration-budget.md

@@ -0,0 +1,81 @@
+# Agent iteration budget
+
+## Problem and meaning
+
+Agent previously converted `max_iterations` to the generic FSM transition limit
+`12 + 8 * max_iterations`. A single-Tool round currently takes ten transitions;
+parallel Tool completions add further transitions. Default ten therefore stopped
+the ninth Tool round before the tenth LLM call. Approval/recovery also creates new
+FSM sessions, so a session counter cannot enforce an execution-wide Agent limit.
+
+`Agent.max_iterations = N` now permits at most N logical LLM calls in one
+AgentExecution, including the first and final call. Tool execution, authorization,
+approval, streaming chunks and backend HTTP retries consume no additional calls.
+This does not bound physical HTTP attempts, tokens, elapsed time or Tool count.
+
+## Owners and dependency direction
+
+| Owner | Responsibility |
+|---|---|
+| Application / Agent declaration | Choose the maximum logical LLM calls. |
+| Agent::IterationBudget | Validate the limit and decide whether another call is allowed from AgentExecution.llm_calls. |
+| Agent preparation operations | Check before context hooks and provider dispatch; capture the limit in execution metadata. |
+| Agent execution/recovery record encoders | Existing durable call identity, result recording and exactly-once recovery interpretation. |
+| Agent::EngineSessionBuilder / InvocationTransitions | Select generic Engine safety mode and a bound appropriate to the Agent phase graph. |
+| Engine::FSMSession | Bound automatic transition chains, without knowing LLMs, Tools, Agent records or iteration policy. |
+| LLMAdapter / RubyLLM backend | Existing logical-call contract, wire transport, response handling and SDK retry policy. |
+
+There is no new mutable Agent counter and no persistence access from Engine.
+The call records already used for context call sequence and recovery remain the
+single authority. InitialPreparation checks before the first call. DispatchPreparation
+includes pending runtime outcomes through the existing record encoder, checks the
+resulting call count, then prepares and commits the next provider dispatch.
+Existing durable pending-call identity prevents unknown outcomes from being
+automatically redispatched. No counter is incremented by Tool or Engine events.
+
+Engine's optional `recursion_limit_scope: :automatic_chain` counts consecutive
+accepted `state_completed` transitions. Only an accepted external transition
+starts a new chain; consumed/stale events or events without a transition do not.
+Agent selects this mode with its declared phase count as the safety bound.
+Engine's default `:session` mode retains the previous total-transition limit for
+Workflow and Tool sessions. Total step count remains available for diagnostics.
+This is a generic mechanism, not an Engine dependency on Agent policy.
+
+ADR-066's allocation remains intact: Agent owns execution and recovery, C09 owns
+one model operation, C06 owns Tool execution, and the backend owns SDK details.
+No RubyLLM, provider-specific or example-specific code is added.
+
+## Completion, suspension and compatibility
+
+- The limit is a nonnegative Integer captured as `agent_max_iterations` in the
+  existing execution metadata at admission. Changing a class declaration during
+  approval cannot increase or reset the active run's budget. No DB schema migration.
+- Resume/recovery uses the saved call records and saved limit. An older execution
+  without this metadata uses the current class limit and records it when preparing
+  another call. Its original limit cannot be reconstructed. Restart from legacy
+  initial preparation captures the fallback before input hooks.
+- A new AgentExecution gets its own limit; handing work to another Agent gives
+  that Agent its own execution budget. GeneratorVerifier/SharedState orchestration
+  limits remain separate policies.
+- A final response on call N succeeds. If call N requests Tools, those Tools
+  finish or await approval normally; the attempted next LLM call then fails with
+  the existing `Phronomy::RecursionLimitError`. Completed Tool results are retained;
+  no final answer or successful application outcome is fabricated.
+- Zero dispatches no LLM call. Invalid limits fail before inference. Default ten
+  and declaration inheritance remain unchanged. Error class is retained; the
+  message now identifies the logical Agent limit rather than an FSM step limit.
+
+This correction may allow more work than the old accidental FSM cutoff, or stop
+an approval-heavy run previously able to reset its session counter. Deploy at a
+quiescent Runtime boundary; do not hot-swap an active process. Application owners
+must assess actual iteration needs after the counting bug is fixed. Increasing
+example limits is not part of this change.
+
+## Verification scope
+
+Regression tests cover nine Tool rounds plus final call ten, streaming, a real
+RubyLLM retry through stubbed HTTP, many Tools in one response, exact cutoff,
+fresh execution, approval and fresh Runtime restoration, recovered provider/Tool
+outcomes, legacy metadata, zero and invalid limits. Generic Engine tests cover
+automatic loops, stale events and unchanged default session limits. Live LM Studio
+acceptance and its independent peg-native parsing failure remain separate gates.

data/docs/architecture/dx05-agent-scope.md

@@ -0,0 +1,126 @@
+# Agent scope and incarnation lifetime (DX05-E core)
+
+An application decides how long it needs an Agent. C04 owns the mechanics for
+acquiring that incarnation and releasing it safely. A scope does not delete saved
+Agents, stop other Agents, close an application-owned Store, or infer whether a
+business operation should be retried.
+
+## Application change
+
+Before, a long-running application could create Agents for each request, but
+the Runtime retained their mutable incarnations until shutdown. `close!` changes
+the durable Agent lifecycle; `purge!` deletes saved state. Neither is a substitute
+for releasing a process-local incarnation.
+
+```ruby
+agent = ReviewAgent.create(persistence: store)
+agent.invoke(text) # the Runtime still owns this incarnation afterwards
+```
+
+After, the application declares the ownership boundary once:
+
+```ruby
+Phronomy::Agent.open_scope do |agents|
+  agent = agents.create(ReviewAgent, persistence: store)
+  agent.invoke_async(text)
+end
+```
+
+`open_scope` waits for a returned TaskResult and returns its resolved value (or
+raises the original exception). A plain block value is returned unchanged.
+It then attempts to unload every Agent it acquired. A Workflow can use
+`agents.create_async` or `agents.load_async` from EventLoop and compose their
+TaskResults. The outer application keeps the scope alive until the Workflow has
+finished. A scope is not serializable Workflow context.
+
+An existing application-owned Agent cannot be adopted by `scope.load`: that
+would give the scope permission to release someone else's object. The attempt
+raises `AgentBusyError`. Repeated load in the same scope returns its live instance,
+after checking class and Store compatibility. A listener cannot be replaced on
+an already live instance. Existing `Agent.load`/`get` lookup semantics remain;
+obtaining a reference does not extend its owning scope's lifetime.
+
+## Release contract
+
+`agent.unload_async` returns `TaskResult<Boolean>` and is EventLoop-safe.
+`agent.unload!(timeout: nil)` waits externally. Both preserve all durable state:
+root and context revisions, journal position, contents, history, metadata and
+lifecycle status. A closed Agent remains closed after reload.
+
+Release requires an exact live owner, no accepted operations or execution
+admission (including approval and recovery waits), and an idle durable execution
+ledger with no retention references. C04 interprets only the presence of opaque
+retention references; their owning domain decides when to remove them.
+
+Concurrent release requests share the pending handle. A successful release
+returns `true`; an already unloaded reference returns `false`. A wait timeout
+does not cancel the release. Store check failure rolls back the reservation and
+preserves the original error. Runtime shutdown closes admission and drains
+already accepted transition completion without creating a replacement Runtime.
+
+New operations cannot enter during release. Old Agent operations fail with
+`AgentUnloadedError` (`code: "agent.unloaded"`, `agent_id`); asynchronous methods
+return failed TaskResults. Immutable snapshots and `agent_id` remain usable.
+A later load creates a new instance and can bind a new listener. The old
+reference cannot mutate or release that new owner. Purged Agents keep their
+existing `AgentPurgedError` semantics.
+
+A concurrent `get` or `load` during release raises `AgentBusyError` immediately;
+it does not wait or create a second owner. Accepted operations make unload fail
+with Busy at its admission gate. In particular, unload inside an Agent terminal
+listener is Busy while that listener is executing. Exit the outer application
+scope after result delivery to release it. Existing immutable local-state reads
+remain available while Runtime shutdown is draining an incomplete transition;
+new execution and mutation admission stays closed.
+
+## Failure and cancellation
+
+Scope tracks materialization receipts before starting work and registers acquired
+Agents before returning them. Closure stops new acquisition and waits for the
+physical completion of accepted materialization, even when its handle was
+cancelled. Indeterminate durable create keeps the C04 recovery reservation and
+logs the Agent ID; it is never silently made creatable again.
+
+Scope does not cancel or wait for unjoined child execution as an implicit
+cleanup policy. An active Agent is retained and cleanup reports `AgentBusyError`.
+If both the main operation and cleanup fail, ScopeCleanupError retains the original
+exception as primary_error/cause and every cleanup failure, plus the retryable scope.
+If cleanup succeeds, the original exception is re-raised with the same identity.
+If the main operation succeeded, failed cleanup raises `Agent::ScopeCleanupError`
+(`code: "agent.scope_cleanup_failed"`). `result` preserves the successful value;
+`failures` is an array of `{agent_id:, error:}` with the original exceptions.
+All acquired Agents are attempted. No automatic retry, purge, or retention
+removal is performed.
+
+## Responsibility and ordering
+
+- C04 owns scope receipts, exact incarnation identity, operation admission,
+  busy/retention rules, invalidation and cleanup errors.
+- C07 supplies the existing transaction boundary. C04's Agent Store supplies
+  `assert_idle!`, `guard_agent!` and retention reads; neither Persistence nor
+  physical Storage gains incarnation release policy.
+- C13 supplies existing TaskResult and physical-completion contracts. It gains
+  no scope membership, Agent busy rules or unload states.
+- Engine supplies existing worker execution, serial EventLoop delivery and
+  shutdown participation. It gains no Agent-specific states.
+- The operation lease and release reservation share the C04 ownership mutex.
+  No Store transaction, Runtime call, application callback or blocking wait runs
+  under that mutex. Accepted runner continuations use C04 internal snapshots;
+  callbacks initiating a new public operation must acquire a new lease.
+- Agent operation completion is distinct from cancelling its public handle.
+  C04 acknowledges release after domain terminal/listener delivery and physical
+  worker completion. A queued or physically running cancelled operation still
+  blocks release.
+
+For notifications, finish child processing, drain notifications, then exit the
+Agent scope. `run_once` retains its existing Store and lifetime behavior; merely
+calling it does not opt into scope cleanup.
+
+This is P5 (core). P6 migrates application examples and performs cross-repository
+acceptance against the published or pinned candidate core.
+
+## Structured-output lifetime update
+
+Scope now exposes `release!` and retains only failed owners for retry. CleanupError
+also carries scope, resolved result and primary_error. The exact Task/error/release
+rules are specified in [structured output and scope](structured-output-and-scope.md).