phronomy 0.29.0 → 0.30.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ee0a6e2cc02a9014a1f6b4b0587474255697960b0e1589070a7846d038452ad
-  data.tar.gz: eb866c788b4dbaf5c560ec0a6a9fe1ef641d630932c7f4309c5ca0741dce2ad0
+  metadata.gz: 077db55116aa3b2b1deeeabef69b46b5481c72f1636aa4c623ad8b843d20ef38
+  data.tar.gz: 07bbf1214b2aaaf6df1403c69ff8e9f7a7bc4bc8dac63ec4a7a1b11955c0a014
 SHA512:
-  metadata.gz: a4970e936adca3d87ee8a8a18469630a563df8fb8a07f06796f4a4bfcae3b1e97b67a51869fdbb68760892201deb12f5f765c082cdfe8559c5f6d0c5ad10dd1a
-  data.tar.gz: 10c461ef9e86a476cc73020dc1167d6b80564f02f47c3da0161a7da8a34953be96efa236ebcfdf938c7b8a5bfeb2ea6ad3fdaca137d6f70cd5238a71bd6cb829
+  metadata.gz: a28ae543ff3826e964cd235580a01175446187546f5f2c94ed34bf12cfd967337df9673654b3029d9173f99479cc32ef966f5bac71db2918cd0265402860e124
+  data.tar.gz: ca6dbea79bc432cb1802dbec83cae8b427011b6782f11cfce02fa30ec5b5003439e6b4e6fedd48b6a589ba6b9374075491ae796549dabe41746f20c43f2ee143

data/CHANGELOG.md

@@ -12,7 +12,113 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
-### r8 first implementation unit (breaking, unreleased)
+## [0.30.1] - 2026-10-24
+
+### Documentation
+
+- Translate historical r8 unit 1/2 architecture notes and durable semantic
+  coordination records into English, preserving API names, executable commands,
+  requirement IDs, dates and the original validation limits.
+- Repair ADR-029's link to the recovery-contract document and its English heading.
+
+Runtime behavior, public APIs and dependency requirements match 0.30.0.
+
+## [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,
@@ -35,10 +37,13 @@ tracking `main` directly.
 
 See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
 
-The following application APIs are part of unreleased development:
+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) |
@@ -62,15 +67,21 @@ Then run:
 bundle install
 ```
 
-Phronomy 0.28 requires RubyLLM 2.0.x. Faraday 2.1.0 is the tested minimum
-supported version; the `~> 2.1` requirement allows versions from 2.1 up to,
-but excluding, 3.0. CI checks fresh dependency resolution and the exact minimum
-with MCP 1.0.0. 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|

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

@@ -83,8 +83,9 @@ 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 the main operation failed, its same exception is preserved and secondary
-cleanup failures are logged with Agent IDs. Logger failure cannot replace it.
+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.
@@ -117,3 +118,9 @@ 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).

data/docs/architecture/error-api-review.md

@@ -52,16 +52,16 @@ that every possible backend failure has been injected.
 | C01 | invoke/admission, TeamExecutionRepository.create_active/save/assert_idle!: active Team run | TeamBusyError with team_id and team.busy replaces AgentBusyError only for Team ownership. Child-Agent failures retain their own classes. No AgentBusy alias or inheritance. | execution_constraint_translation_spec; shared SQL coordination contract |
 | C01 | HandoffRunner.invoke/cancel, Orchestrator fan-out, operation rejection | Retain ConfigurationError, HandoffError, StateConflictError, recovery requirements and on_error policy. Missing retained children are not missing Teams. Readback reconciliation may itself fail and does not prove absence. OperationRejected stays private; public code team.enqueue_after_finalize is unchanged. | durable_coordination_spec; integration/team_coordinator_spec; SQL reason diagnostics |
 | C02 | Workflow definition/action, WorkflowContext writes, state CAS, waiting/resume | Retain ConfigurationError, WorkflowContextOwnershipError, WorkflowAsyncActionError and persistence conflict. Workflow has no equivalent target-root load API to justify another NotFound class. DX05-D adds WorkflowTaskResumeError with workflow.task_resume_unsupported only for unsupported restoration of a task-state phase, before any start side effect. Start/source/apply failures keep their original errors, and task cancellation remains distinct from a failed CancellationError. Agent scope is separate. | workflow and execution unit/integration suites; task_state_spec; shared SQL task-state contract (live PostgreSQL acceptance pending) |
-| C03 | GeneratorVerifier.invoke; parse fallback and confidence decision | Preserve ParseError-only fallback and LowConfidenceError.result. Add optional constructor code; do not absorb provider/callback errors into a GenerationError. | generator_verifier specs; error_api_diagnostics_spec |
+| C03 | GeneratorVerifier.invoke; schema-qualified confidence decision | Agent owns OutputError; Generation records output_failed with its diagnostic; GeneratorVerifier::UnacceptedResultError carries Result and an optional code. CleanupError retains cleanup and primary failures. See generator-verifier-lifecycle-result.md. | generator_verifier specs; error_api_diagnostics_spec |
 | C04 | Base.load, create/get, invoke/resume/purge | Add AgentNotFoundError only at the requested root. Journal/content/execution absence remains persistence failure. Preserve foreign AgentNotFound identity. AlreadyExists/Busy/Purged, uncertain purge and recovery-required retain their meaning. | error_api_boundaries_spec; Agent lifecycle/recovery suites |
 | C04 | stream listener policy; result/failure persistence | StreamCallbackError keeps event_type/original_error/result, with optional code. Listener :fail_task versus :log_and_continue remains explicit; no unconditional callback swallowing. | stream_callback_error_policy_spec; error_api_diagnostics_spec |
 | C05 | Assembly.prepare and policy invocation; plan/budget validation | Keep BudgetExceededError and ManifestError. Reuse C15 public trace_with, metadata only; a finish failure cannot mask policy failure or export the returned context. | error_api_boundaries_spec; Context suites |
 | C06 | Tool.call / native async operation; schema, execution, async handle validity | Keep ToolError class; supply tool.invalid_arguments / tool.execution_failed / tool.invalid_async_result at owned conversion sites. Explicit async cause fixes delayed-failure information loss. Existing ToolError/cancellation pass through unchanged. :suppress survives logger failure. | tool/async_operation_spec; tool/base_spec; schema_error_spec |
 | C07 | StorageBoundary, transaction, SaveOutcome, SnapshotComparison | Retain known-category mapping and original cause. Unknown I/O/application failures pass through. Keep committed/not_committed/unknown separately from exception class; no code-based reconciliation. | storage_boundary_spec; failure_contract_spec; snapshot_comparison_spec; SQL suites |
 | C08 | fetch, fetch_text, fetch_json and content identity | Invalid requested JSON is IntegrityError with content.invalid_json and original ParserError; invalid UTF-8 is content.invalid_encoding. Raw fetch failures pass through; no dependency on OutputParser. Requesting JSON for plain text is also invalid representation, not proof of physical corruption. | error_api_boundaries_spec; content conformance; SQLite |
-| C09 | LLM complete/stream, request/result checks, RubyLLM conversion | Keep Authentication/RateLimit/ContextLength as TransportError children and InvalidResult separate. Unknown exceptions, cancellation and callbacks retain identity. Existing SDK conversion is not an automatic retry policy. | LLMAdapter unit/integration suites |
+| C09 | LLM complete/stream, request/result checks, RubyLLM conversion | Authentication/RateLimit remain TransportError children; ContextLength and InvalidResult remain separate. The RubyLLM backend also maps identified Faraday TimeoutError/ConnectionFailed to TransportError with the original cause chain. Unknown exceptions, cancellation/deadlines and callbacks (including same-class Faraday failures) retain identity. Classification does not imply retry safety. | LLMAdapter suites; transport_error unit and real-HTTP integration contracts |
 | C10 | VectorStore add/search/remove/clear/size and AsyncClient | Keep InvalidResultError for invalid response and driver communication errors unchanged. Driver-specific transaction/effect uncertainty is not normalized without a backend-specific contract. No universal VectorStore TransportError or sibling-contract borrowing. | VectorStore and async-client suites; live PG/Redis pending |
-| C11 | Embeddings.embed / AsyncClient; RubyLLM errors | Add owner-local AuthenticationError and RateLimitError under existing TransportError. Callers can request credentials versus surface quota refusal. Other SDK errors retain TransportError; arbitrary I/O failures, cancellation and programming errors are not guessed to be SDK failures. | error_api_boundaries_spec; embeddings/async_client_spec; RubyLLMEmbeddings specs |
+| C11 | Embeddings.embed / AsyncClient; RubyLLM errors | Owner-local AuthenticationError and RateLimitError remain under TransportError. Other RubyLLM errors and identified Faraday TimeoutError/ConnectionFailed map to TransportError in the concrete backend, preserving causes. Arbitrary I/O failures, cancellation/deadlines and programming errors are not guessed to be SDK failures. | error_api_boundaries_spec; embeddings/async_client_spec; transport_error unit and real-HTTP integration contracts |
 | C12 | Records.read/fetch, conditions/unique constraints, streams/blobs, atomic views | Keep nil read versus raising fetch; preserve condition/resource/constraint. Add optional code to specialized constructors; SPI 2 and storage format unchanged. No Agent or Persistence semantics in the backend. | storage SPI snapshot; backend conformance; SQLite |
 | C13 | TaskResult completion, map/flat_map/all_settled, wait/timeout/cancel | Transport errors unchanged. Observer failure leaves settled result intact and continues later observers even if logging fails. Transformation failure settles the derived task. Outcome attributes and physical completion remain separate. | task_result_spec; error_api_boundaries_spec; async composition suites |
 | C15 | Base.trace, trace_with, OpenTelemetry.trace, Automatic | Explicit tracing propagates start/finish-only failure. After a primary business failure finish is attempted once and secondary report failure is suppressed. No finish after start failure. OpenTelemetry keeps with_span context. Automatic retains best-effort observation policy; Langfuse keeps its adapter-specific network suppression. | tracing/base_spec; open_telemetry_tracer_spec; automatic and extension specs |
@@ -211,7 +211,7 @@ Ripper inspected 339 Ruby files. The following 63 definitions include base, priv
 | `Phronomy::SchedulerReentrancyError` | `Phronomy::EventLoopReentrancyError` | `lib/phronomy/execution/scheduler_reentrancy_error.rb` |
 | `Phronomy::TimeoutError` | `Phronomy::Error` | `lib/phronomy/execution/timeout_error.rb` |
 | `Phronomy::FilterBlockError` | `Phronomy::Error` | `lib/phronomy/filter/filter_block_error.rb` |
-| `Phronomy::LowConfidenceError` | `Phronomy::Error` | `lib/phronomy/generation/low_confidence_error.rb` |
+| `Phronomy::GeneratorVerifier::UnacceptedResultError` | `Phronomy::Error` | `lib/phronomy/generation/generator_verifier/unaccepted_result_error.rb` |
 | `Phronomy::Integrations::OrderedEventDelivery::ClosedError` | `Phronomy::Error` | `lib/phronomy/integrations/ordered_event_delivery.rb` |
 | `Phronomy::Integrations::OrderedEventDelivery::OverflowError` | `Phronomy::Error` | `lib/phronomy/integrations/ordered_event_delivery.rb` |
 | `Phronomy::LLMAdapter::AuthenticationError` | `Phronomy::LLMAdapter::TransportError` | `lib/phronomy/llm_adapter/authentication_error.rb` |

data/docs/architecture/generator-verifier-lifecycle-result.md

@@ -0,0 +1,126 @@
+# GeneratorVerifier: approval, lifetime and result contract
+
+Generation (C03) is a responsibility group, not a Ruby namespace.
+Phronomy::GeneratorVerifier is the public draft/review/retry API. Applications
+choose the Agent classes, Tools, prompts, evaluation thresholds and authorization
+policy. Generation owns composition and evaluation; Agent (C04) owns Tool
+authorization, durable execution, cancellation and safe unload.
+
+Correct behavior takes priority over backward compatibility. This change removes
+trusted/trusted?, raise_if_untrusted and LowConfidenceError. There are no legacy
+aliases or compatibility branches.
+
+## Application operations
+
+Construct with new or open. Construction acquires both owned Agents, synchronously;
+a failure acquiring the second releases the first. Prepare the pipeline before
+entering EventLoop. Both Agents and their conversations are reused between
+invocations. open requires a block, returns its value, and always attempts release!.
+A directly returned TaskResult is awaited once before release; arrays and nested
+Tasks are not recursively awaited. See [structured output and scope](structured-output-and-scope.md).
+
+invoke waits for the final Result. invoke_async returns TaskResult. A pipeline
+admits one invocation at a time; independent concurrent conversations need
+independent pipelines. Workflow state, approvals and cancellation are per invocation.
+config is forwarded to Workflow. Only the private cancellation token and any
+InvocationContext are forwarded to Agent operations, not Workflow-specific
+identity or settings.
+
+on_approval receives an Approval with invocation_id, phase (:draft/:review) and
+request (Agent::ToolApprovalRequest). It is a short, thread-safe notification,
+not a blocking UI callback or a function whose return value authorizes a Tool.
+Use approval.respond_async(approved: true/false), or enqueue the Approval for an
+external UI to answer later. The response Task observes the resumed Agent's
+terminal outcome and returns nil. Do not wait for it inside the callback.
+
+Without a callback, approval_requests exposes notifications issued in the current
+invocation, including answered ones. It is not a mirror of current durable
+approval state. Suspension is not an error and no implicit approval or denial is
+performed. Expiry and cancellation are application choices. Stale invocation
+handles fail; Agent validates execution/request identity and duplicate decisions.
+Invalid replies fail their own Task without cancelling the original invocation.
+Callback exceptions cancel the owned invocation and remain its primary error.
+
+cancel_async requests cancellation without mutating a caller-owned cancellation
+token. It can also address a known Agent execution after a Handoff outcome.
+Completion acknowledges the cancellation operations, not physical quiescence;
+observe the invocation result separately. release! delegates safety to Agent's
+unload!, preserves saved history and does not close the Store. It rejects active
+invocations rather than cancelling or denying approvals implicitly.
+
+All owners are attempted during release. Successful owners are removed; failed
+ones remain available for cancellation or another release attempt. Partial release
+cannot be followed by a new invocation. Successful release is idempotent (true,
+then false). CleanupError exposes pipeline, failures, result and primary_error;
+when both application work and cleanup fail, neither exception nor the recovery
+handle is lost. Its cause is the primary exception, if present.
+
+Handoff coordination is outside this composition's contract. A Handoff result
+raises generation.unsupported_handoff rather than leaving the Workflow pending.
+Agent retains authority over durable coordination and safe release; Generation
+never purges unfinished work or clears retention to make cleanup appear successful.
+Reconstructing an in-flight GeneratorVerifier after process restart is not offered.
+
+## Agent cancellation during approval suspension
+
+An approval suspension ends the current FSM session, but the logical execution
+and its original Task remain pending. C04 now retains the cancellation connection
+through this suspension, routes cancellation to its existing quiescence/terminal
+commit barrier, and closes the subscription on resume or termination. Generation
+does not implement this Agent transition itself. Cancellation and approval racing
+at the suspension boundary must not create competing terminal/resume commits.
+
+## Results and decisions
+
+Result is immutable, including nested data. It contains output, confidence,
+confidence_threshold, review_approved, citations, iterations, review_notes,
+termination_reason, interrupted_phase and failure. accepted? describes satisfaction of the
+configured evaluation conditions, not an application's decision to publish.
+
+Confidence is the lower final draft/review score. A completed evaluation is accepted
+only when review_approved is true and confidence meets the threshold. At the
+iteration limit, acceptance wins if both conditions hold; otherwise the reason is
+iteration_limit. Scores and threshold are finite 0..1; max_iterations is a positive
+Integer. Agent validates the fixed output schema without fallback or normalization.
+
+A Tool denial is a normal Agent rejected outcome, not a parser input or automatic
+retry. Result reports tool_rejected and the interrupted phase. Confidence and
+review_approved are nil because the evaluation did not complete. Rejection during
+draft has no output; rejection during review retains the draft. iterations counts
+completed drafts.
+
+to_h includes all fields. Result.from_h accepts that Hash and its JSON round trip,
+rejecting unknown fields, invalid types and contradictory reasons. Citation keys
+are normalized to strings. Equality and hash use all semantic fields, so a change
+in review decision or threshold is observable. Applications own storage/transport
+choices and any intentional projection of these fields.
+
+raise_if_unaccepted defaults to false. When explicitly true, an unaccepted Result
+raises GeneratorVerifier::UnacceptedResultError with result and code. Provider,
+cancellation and callback errors do not become evaluation failures. An Agent
+OutputError becomes output_failed with its phase and diagnostic; there is no automatic
+retry. raise_if_unaccepted preserves that OutputError as the cause.
+
+## Ownership boundaries
+
+C03 depends on C04 Agent, C02 Workflow and C13 Execution. C04 uses C17
+OutputParser to implement its output promise; C03 has no C17 dependency. Cancellation subscriptions use the existing execution abstraction.
+No Agent registry, private Scope construction, Storage operation or Engine
+implementation is accessed from Generation.
+
+Private AgentOperation connects public Agent commands and notifications.
+Invocation owns one call's child observations, subscription lifetime and approval
+routing. WorkflowBuilder/AgentResultReceiver/PipelineState retain graph, event
+conversion and correlated state application. Result owns evaluation facts and
+their invariants.
+
+## Application migration
+
+Use open around the complete application operation, including validation retries.
+Use accepted? and termination_reason, not score-only trusted?. For an external
+approval UI, start invoke_async, enqueue on_approval notifications, respond through
+the original Approval handle, and observe the final Task before release.
+
+examples/19_trust_pipeline is the direct consumer. examples/27_issue_analyzer only
+mentions GeneratorVerifier in descriptive classification text and requires no API
+migration. Full old/new runnable sources are available through the source diff.

data/docs/architecture/generator-verifier-ownership.md

@@ -1,111 +1,20 @@
 # GeneratorVerifier ownership and event contract
 
-## Role and problem
-
-GeneratorVerifier exposes the draft/review/retry pattern. An application supplies
-two Agent classes, prompt builders, optional result parsers and convergence
-settings. invoke runs the Workflow and returns the existing Result, optionally
-raising LowConfidenceError. Agent completion arrives as Workflow events; Workflow
-entry actions return context immediately rather than awaiting Agent Tasks.
-
-R08 and D08 describe the same issue: a 199-line build_workflow mixes the graph
-with Agent startup, response parsing/normalization and failure notification.
-Nested PipelineState also occupies the public facade's source file. Separating
-only the file without removing receiver-to-facade private calls would leave the
-responsibility problem in place.
-
-## Owners and reading order
-
-| Owner | Responsibility |
-|---|---|
-| GeneratorVerifier | Public settings and Result; cached Workflow assembly, invocation, default JSON parser fallbacks and final confidence/raise policy. |
-| GeneratorVerifier::WorkflowBuilder | Draft/review/finalize/failed graph, request IDs, prompt creation, Agent startup and convergence guard. |
-| GeneratorVerifier::AgentResultReceiver | Separate draft/review payload conversion, common terminal-event classification and failure notification to the supplied Workflow. |
-| GeneratorVerifier::PipelineState | Existing Workflow fields, request correlation, stale/duplicate rejection and EventLoop-owned state mutation. |
-
-The last three constants are private. WorkflowBuilder and AgentResultReceiver
-are new internal classes; PipelineState is the existing class moved with its
-body and canonical name unchanged. The implementation lives in three files under
-generation/generator_verifier. The public facade and Result keep their names and
-locations; no loader changes or compatibility aliases are introduced.
-
-The initial D08 sketch suggested multi_agent/generator_verifier_workflow.rb.
-Since the prior layout work established generation as this pattern's owner,
-the internal files now stay there instead of creating a second feature owner.
-The new directory adds a module in directory-based analysis, not a public API.
-
-WorkflowBuilder#build reads as a graph: named entries, then ordered transitions.
-start_draft/start_review describe request preparation and dispatch. The receiver's
-draft_payload and review_payload retain different meanings. Their common listener
-has only the two internally selected phases; it is not a public configurable
-pipeline. It shares the same terminal/error rules rather than combining response
-formats into an options-driven generic parser.
-
-Default parsers remain explicit callables captured by the facade. Clamp and
-citation normalization move to their receiver owner. The old __send__ calls back
-to facade helpers disappear. The existing private Agent event-sink entry point
-is still called via send; changing that cooperation API is outside this scope.
-
-## Preserved ordering and failure contract
-
-- Each Agent is constructed once, lazily during the first successful Workflow
-  build. The cached Workflow and Agent instances are reused. Each invoke gets a
-  fresh Workflow context. No locking or new concurrency policy is introduced.
-- Each request gets a new UUID and a merged context before prompt construction.
-  The listener captures that request ID and the context's stable Workflow ID.
-  Workflow closures see the completed Workflow assignment before any entry runs.
-- Entry actions start asynchronous Agent work and return next_state, never a
-  TaskResult. Inline completion remains valid because signal queues a Workflow
-  event. Unknown/nonterminal Agent events are ignored.
-- done parses output, normalizes the phase-specific payload and signals the
-  matching completed event. StandardError from parsing, normalization or success
-  notification is signalled as the corresponding failed event with the same
-  exception object. Failure-notification exceptions are not retried or wrapped.
-- error/timeout/cancelled use the payload error or the same phase-specific
-  fallback message. approval_required remains a pipeline failure. A false return
-  from signal is returned without a retry or a new failure event.
-- PipelineState accepts only the current request ID. It clears the accepted ID,
-  increments iteration after draft completion, appends feedback after review,
-  and consumes old/duplicate results before any transition. The receiver does
-  not mutate context or add its own deduplication; stale done payloads can still
-  be parsed before the state rejects their correlated event.
-- Review completes when both the lower normalized score meets threshold and
-  approval is literal true, or when the iteration limit has been reached.
-  Otherwise it returns to draft and passes the last feedback to its prompt.
-- Final Result trust remains confidence >= threshold. At the iteration limit,
-  high confidence with approved=false can therefore still produce trusted=true.
-  A nonpositive limit still executes one draft/review cycle. These are observed
-  existing semantics, not behavior fixes hidden in this extraction.
-
-Public initialize/invoke parameters, Result fields/trusted? alias, parser
-fallbacks, score/citation normalization, error messages and PipelineState fields
-remain unchanged. Agent/Workflow/Engine/Storage behavior and SQL are not modified.
-Private clamp/normalize_citations implementations relocate; private overrides are
-not treated as additional supported public APIs.
-
-## Verification and trade-off
-
-Thirty-nine behavior examples pass unchanged on Refactor 40 and the candidate.
-They cover inline completion, ignored progress, pending Task returns, both phases'
-error/timeout/cancelled/approval failures, parser and notification failures,
-request correlation, duplicate/old callbacks, clamping, literal approval, final
-trust, iteration limits, caching, fresh state and config forwarding. Existing
-delayed-callback and WebMock integration examples cover the real Workflow path.
-
-A separate process comparison preserves public methods, parameters, constants,
-Result shape, the private state name/field schema/defaults and Runtime inactivity.
-Stable/Beta snapshots do not list GeneratorVerifier, so this explicit comparison
-supplements those existing gates. Core/integration/examples/real SQLite, type,
-style, annotations and isolated gem checks are included in distribution evidence.
-Live PostgreSQL, live LLM, candidate CI and performance are not run for this scope.
-
-The facade is 369 -> 118 lines. Workflow definition is 199 -> 34 lines, with a
-12-line facade assembly method. The three internal files are 112/89/57 lines,
-for 376 total, seven more than before. Two new classes and one moved class cost
-additional files; they give graph, receiver and state independent reading units.
-Directory-level dependency counts increase with that physical partition; cycle
-membership is unchanged. This is responsibility separation, not cycle removal.
-
-Refactor 41 is applied and independently verified at core e87eb77f, tree
-14dc8a546a4fd96e19e0713f7480ca2efa3c331a. All nine files and the full tree match.
-R08/D08 is closed. The published diagram is applied41-01. R09 and R10 remain.
+The current contract is
+[GeneratorVerifier: approval, lifetime and result](generator-verifier-lifecycle-result.md).
+
+GeneratorVerifier is the public owner of draft/review Agent composition and its
+evaluation Result. AgentOperation delegates to public Agent commands. Invocation
+owns per-call approval routing, cancellation subscriptions and child observations.
+WorkflowBuilder builds the graph; AgentResultReceiver converts results;
+PipelineState applies correlated events; Result owns immutable evaluation facts.
+
+Both owned Agents are acquired at pipeline construction and reused until release.
+Workflow contexts are fresh for each invocation. Concurrent use of one pipeline
+is rejected. Approval suspension remains pending and is exposed to the application;
+it is not converted to failure. Tool denial is a tool_rejected Result.
+Handoff is explicitly unsupported instead of silently leaving completion pending.
+
+The older R08/D08 and R8 unit15 documents record the historical extraction. Their
+preserved score-only trust, approval-failure and lazy Agent acquisition behavior
+has been superseded by the current contract.