phronomy 0.29.0 → 0.30.0

data/docs/architecture/llm-continuation-metadata.md

@@ -0,0 +1,88 @@
+# LLM continuation metadata preservation
+
+This correction follows [ADR-066](../decisions/066-llm-and-tool-operation-contracts.md).
+It does not change the LLM/Tool/Agent ownership decision, add a dependency to the
+contract, or teach Agent a provider wire format.
+
+## Problem and contract
+
+The RubyLLM backend converted SDK responses into Phronomy Response values without
+their reasoning data. A later model turn therefore lost information RubyLLM could
+otherwise replay. Saved assistant records already contained Message metadata, but
+RuntimeInput reconstructed only model_id. Explicit Message imports dropped the
+metadata too. These were separate losses along the same conversation path.
+
+C09 Message/Response metadata remains immutable canonical JSON. Backend-owned
+continuation data accompanies its assistant message through a Tool round, Journal
+serialization, recovery and explicit Phronomy-message import. Agent preserves the
+value without inspecting its backend keys. Metadata does not authorize a Tool,
+change context selection, become answer content or become arbitrary SDK options.
+Record/control metadata remains distinct from metadata inside an assistant payload.
+
+The concrete RubyLLM backend owns the ruby_llm_continuation namespace, format
+version 1, and conversion of SDK thinking text/signature and raw_reasoning. It
+reconstructs those SDK options only inside the backend. RubyLLM still owns wire
+format rendering; no SDK class or provider registry is patched for this fix.
+No thinking toggle, extra model call, fallback, retry, sampling change or Tool
+execution is introduced. Existing Tool thought_signature behavior is unchanged.
+
+Streaming's final Response retains the same continuation data. Public content
+chunks remain answer chunks; this change adds no reasoning-display event API.
+SDK token usage semantics are unchanged.
+
+## Replay compatibility
+
+The backend records the requested model ID, provider, selected protocol name and
+a SHA-256 of the API base. The endpoint itself and credentials are not stored in
+the envelope. Reuse requires an exact match of this scope and format version.
+An incompatible scope/version raises ConfigurationError before sending the next
+model request. State is neither silently discarded nor sent to a different target.
+Malformed envelopes fail explicitly. Legacy messages without the envelope remain
+usable; missing historical reasoning cannot be reconstructed.
+
+This conservative equality check is not a claim that all identical endpoints are
+semantically unchanged, or that different models can never share reasoning. It
+does not detect server runtime/template changes behind one URL, account changes,
+or model replacements behind one model ID. Cross-model/provider reasoning
+conversion is outside this correction.
+
+Handoff continues to use its existing context selection policy. If a selected
+assistant message carries this state, a same-scope target can replay it and a
+different-scope RubyLLM target rejects it. Applications requiring transfer across
+incompatible scopes must intentionally select/derive portable context using the
+existing context policy; they must not forge the scope or treat metadata as
+authority. Other backend implementations own their own metadata conventions.
+
+## Persistence and compatibility
+
+There is no DB schema change, new SDK object in storage, or changed public method
+signature. RuntimeInput restores the canonical metadata Hash and uses historical
+top-level model_id only when metadata does not already contain it. Canonical
+metadata is authoritative if both representations exist. Missing metadata means
+an empty Hash; malformed non-Hash metadata is rejected.
+
+ContextImporter preserves explicitly supplied canonical Message metadata. It does
+not inspect an externally supplied RubyLLM object's thinking field; converting
+SDK-specific external histories remains a backend-boundary concern, not a new
+Agent SDK dependency. Signed/provider-shaped values stay unmodified and subject
+to the SDK 2.0.0 representation supported by the existing dependency constraint.
+This is not general preservation of every SDK field (for example server-tool
+raw_content), nor a promise of compatibility with untested providers.
+
+## Evidence and acceptance
+
+The compatibility regressions are:
+
+- spec/phronomy/llm_adapter/continuation_metadata_spec.rb: actual SDK parsing and
+  rendered HTTP for text/signature, streaming, Responses encrypted state and
+  provider-shaped OpenRouter reasoning; scope/version rejection and legacy input.
+- spec/phronomy/agent/continuation_metadata_spec.rb: real Agent Tool loops,
+  subsequent invocation, approval across reconstructed storage/Runtime, Handoff,
+  and an independent backend with opaque metadata and no RubyLLM calls.
+- spec/phronomy/agent/ruby_llm_materializer_spec.rb: historical model_id reading.
+
+The LM Studio gpt-oss-20b reasoning omission was independently reproduced before
+this change. The prior isolated A/B diagnostic returned HTTP 200 in all four
+trials. This correction therefore does not claim to explain or fix peg-native
+HTTP 400, nor to complete Example 22. Actual model behavior and the entire
+application acceptance remain separate verification stages.

data/docs/architecture/lm-studio-output-failures.md

@@ -0,0 +1,111 @@
+# LM Studio provider output failures
+
+## Scope and ownership
+
+`Phronomy::LLMAdapter::LMStudio` is an explicitly selected concrete RubyLLM
+backend. It handles rejection of the provider's generated conversation format.
+It does not parse or repair partial model output, change prompts or sampling
+parameters, split Tool/schema requests, or replay Agent/Workflow/Tool work.
+The default `RubyLLM` backend and SDK global configuration remain unchanged.
+
+C09 owns the meaning of the public `TransportError` reason code
+`llm.provider_output_parse_failed`. A code does not itself authorize retry.
+The concrete backend owns HTTP-body decoding and its transport policy under
+ADR-011/066. Application composition selects that backend and its retry limit.
+No new Contract or Contract dependency is required.
+
+## Recognition and evidence limits
+
+Recognition requires a RubyLLM BadRequestError/ServerError with its own HTTP
+response and actual HTTP status 400 or 500. The JSON body must contain `error`
+with the exact engine code 500, type `server_error`, and message:
+
+    The model produced output that does not match the expected peg-native format
+
+The engine object may be direct, or JSON after the exact LM Studio prefix
+`Engine protocol predict stream returned an error: `, carried in an error string
+or the error object's message field. No search through arbitrary strings or
+nested exception causes is performed. A malformed/unknown envelope, missing
+response or different status/type/code/message remains an ordinary SDK failure.
+The original SDK exception remains `cause`; the original HTTP status and body
+are not rewritten. The engine's internal 500 is not treated as HTTP 500.
+
+The offline HTTP fixture envelopes are synthetic. Follow-up real LM Studio
+acceptance on 2026-10-24 captured the actual HTTP 400 error body and confirmed
+classification as `llm.provider_output_parse_failed`. The eligible request was
+resent once with identical bytes. After the retry also failed, the adapter
+returned the final TransportError at its own limit; the measurement guard did
+not trigger, and Agent/Workflow work was not replayed. A separate application
+invocation completed initially with HTTP 200. Total: two application invocations
+and three generation POSTs; this is not recovery within the failed invocation.
+
+Live error identification and bounded retry are verified. Recovery by retry,
+recovery rate, the PEG root cause and recurrence resolution remain unverified.
+The unrecognized-envelope branch was not observed live. The failing host logs
+contain parser suffixes but do not establish the complete pre-parser token
+stream. Unknown formats fail closed without retry.
+
+## Retry policy and configuration
+
+```ruby
+context = RubyLLM.context do |config|
+  config.openai_api_base = "http://127.0.0.1:1234/v1"
+  config.openai_api_key = "lm-studio"
+  config.openai_protocol = :chat_completions
+  config.request_timeout = 120
+end
+
+Phronomy.configure do |config|
+  config.llm_adapter = Phronomy::LLMAdapter::LMStudio.new(
+    context: context,
+    max_parse_retries: 1 # default 0; only 0 or 1 is accepted
+  )
+end
+```
+
+The selected backend snapshots the RubyLLM 2.0 context and disables SDK retries
+within that snapshot. **Ordinary 429/500/network retries are also disabled for
+this backend.** Applications needing the existing SDK transport policy should
+keep the default RubyLLM backend; this selection is deliberately explicit.
+The caller's context and global settings are not modified. The frozen snapshot
+prevents later scalar context changes from increasing the retry budget.
+
+Only a recognized parse failure can trigger the optional second attempt. It is
+limited to non-streaming `complete`, provider `openai`, model
+`openai/gpt-oss-20b`, no advertised Tools, no response schema, and no Tool messages
+or pending Tool calls in the supplied history. The same immutable request is
+used to construct a fresh operation-local SDK chat. Total generation POSTs are
+at most two. The one-additional-attempt limit is a conservative policy choice,
+not an empirically established optimum or a reliability guarantee.
+
+Streaming is never replayed. Delivered chunks and application callback exception
+identity are preserved. Cancellation is checked before another attempt; existing
+worker lifetime and deadline behavior remain unchanged. A final failure exposes
+the final SDK exception as cause. No successful result is synthesized from an
+error body.
+
+## Observation
+
+The existing logical `llm.call` span covers the complete adapter operation.
+There is no new trace identity or dependency from C09 to C15. Individual SDK HTTP
+requests continue to use RubyLLM's instrumentation. Every failed adapter attempt
+also emits a safe warning containing attempt number, reason code, actual HTTP
+status when known, and whether a retry was selected; no prompt, raw body or
+credential is included. Therefore a later success does not erase the first
+failure from the diagnostic record.
+
+An optional concrete-backend `on_attempt:` callable receives these safe fields
+plus `outcome`. It must support concurrent calls if an adapter is shared and is
+not a durable audit store. Logging/callback failures cannot replace the business
+result or original exception. Applications can use SDK instrumentation when they
+need request correlation or detailed HTTP evidence. Successful response events
+do not invent an HTTP status that the public response does not expose.
+
+## Verification
+
+Offline contracts use a real loopback TCP HTTP server and the actual
+RubyLLM/Faraday stack. They verify status/cause fidelity, default no retry, exactly
+two POSTs for opt-in recovery/exhaustion, unchanged request JSON, excluded
+requests, cancellation between attempts, callback identity, unknown responses,
+configuration isolation and unchanged default-backend SDK retries. They do not
+invoke a live model.

data/docs/architecture/r8-unit15.md

@@ -1,5 +1,8 @@
 # r8 unit15: Generation contract boundaries
 
+> Historical contract: parser injection/fallback is superseded by
+> [structured output and scope](../architecture/structured-output-and-scope.md).
+
 This responsibility refactor is based on applied unit14, commit
 `97c3d76b35594bb971a60a2932410ddf22e48d3a` (tree
 `c326196212a4ac369294a9ccb936619813e51250`).

data/docs/architecture/r8-unit7.md

@@ -6,7 +6,8 @@ all of C04, C06 or the overall target complete.
 
 | Owner | Responsibility after this change |
 | --- | --- |
-| Agent InvocationTransitions | Phase vocabulary, ordered automatic/external transitions, guard evaluation, iteration bound |
+| Agent IterationBudget | Logical LLM-call limit over durable AgentExecution records; see [iteration budget](agent-iteration-budget.md) |
+| Agent InvocationTransitions | Phase vocabulary, ordered automatic/external transitions, guard evaluation, automatic-chain safety bound |
 | Agent InvocationActions | Prepared input, LLM dispatch, Tool batch orchestration and result/event interpretation |
 | Agent ExecutionCoordinator / RecoveryCoordinator | Admission, durable preparation, approval, terminal outcome, recovery and causal revision checks |
 | Agent ExecutionEnvironment | Private process-local connection required by the Agent framework; session construction/registration, serial owner and operation submission |

data/docs/architecture/structured-output-and-scope.md

@@ -0,0 +1,183 @@
+# Structured Agent output and application lifetimes
+
+This contract supersedes the parser fallback described in the earlier Generation
+ownership documents. Agent owns the promise made by `output_schema:`; Generation
+owns the draft/review protocol and evaluation; the application owns publication,
+authorization and any decision to start another attempt.
+
+## Public behavior
+
+`Agent::Base#invoke`, `invoke_async`, `stream`, `stream_async` and
+`start_reserved_async` accept `output_schema: nil`. `run_once` forwards this option.
+Without a schema the existing free-text behavior remains. With a schema, successful
+`output` and `result` are deeply frozen JSON objects with String keys; `raw_output`
+preserves the model text. Token events are provisional, not validated objects.
+The final Task and terminal event are produced only after validation. Output
+filters run before validation and cannot silently break the promised shape.
+
+```ruby
+schema = {
+  type: "object", properties: {answer: {type: "string"}},
+  required: ["answer"], additionalProperties: false
+}
+value = Phronomy::Agent.open_scope do |scope|
+  agent = scope.create(AnswerAgent)
+  agent.invoke_async("Explain the result", output_schema: schema)
+end
+puts value.fetch(:output).fetch("answer")
+```
+
+C17 `OutputParser::JsonSchemaParser.new(schema:).parse(text)` performs strict JSON
+decoding and JSON Schema validation. It does not extract fenced JSON, remove model
+control tokens, coerce numbers, clamp scores or repair missing fields. Duplicate
+keys, comments, invalid escapes, control characters and nonfinite values fail.
+Existing extraction-oriented parsers remain available for their separate purposes;
+they do not define Agent's structured-output guarantee.
+
+The supported vocabulary is `$schema`, `$defs`, `$ref`, title, description, type,
+enum, const, anyOf, properties, required, additionalProperties, items, minItems,
+maxItems, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf,
+minLength, maxLength and pattern. The root must declare type object. Nested nullable
+values and local JSON Pointer references are supported; external/cyclic references,
+unknown keywords, invalid patterns and invalid schemas are rejected before model
+or Tool execution. The dialect is JSON Schema 2020-12. Schema input accepts JSON
+values and String/Symbol keys, snapshots recursively, and rejects duplicate normalized
+keys, Ruby objects and cycles. Generic schema interpretation belongs to C17, not
+Tool::Schema, Agent's caller or Generation.
+
+## Native transport and completion facts
+
+C09 `LLMAdapter::Request#response_schema` carries the immutable schema; each model
+turn retains it. RubyLLM `with_schema` sends native schema configuration. The
+transport tests cover RubyLLM 2.0.0 OpenAI/Azure Chat Completions and Responses,
+Anthropic, Gemini and Ollama's OpenAI-compatible endpoint. Constraints are compared
+with the actual HTTP payload. SDK removal of root schema/title annotations does not
+change validation. These are offline protocol tests, not certifications of every
+remote model. Known model capability failures and native schema rejection raise
+`LLMAdapter::StructuredOutputUnsupportedError` (`llm.structured_output_unsupported`).
+Unregistered OpenAI-compatible local models may attempt native schema delivery.
+Other providers are rejected explicitly for structured requests until their native
+transport has been verified. There is no downgrade to JSON mode or prompt-only
+instructions. Tool capability is checked too when the model catalog is available;
+remote schema/Tool combination rejection remains a provider failure.
+
+LM Studio's HTTP 400 string error `Cannot combine structured output constraints
+with lazy grammar` is a known native schema/Tool rejection. It is classified as
+`StructuredOutputUnsupportedError` with its original cause, for both complete and
+stream operations. Unrelated string errors and requests without a schema retain
+their ordinary transport-error behavior. The adapter neither downgrades schemas
+nor replays requests. RubyLLM's configured transport retry policy is independent.
+The minimum Faraday streaming callback omits the HTTP status, so RubyLLM may
+surface this same exact rejection as `ServerError`; its cause is preserved too.
+That synthetic server status can trigger SDK retries before the adapter receives
+the error. Adapter replay tests disable SDK retries to verify their own boundary.
+
+`Response` records finish_reason (stop, tool_calls, length, content_filter, refusal,
+unknown), refusal and raw_finish_reason metadata. Only normal final completion can
+be a structured success. Tool requests are intermediate; they retain existing
+approval, denial, cancellation and recovery behavior. RubyLLM 2.0 loses streamed
+refusal fields in Chunk values; operation-local Protocol subclasses capture these
+raw facts. No SDK global class or shared protocol registry is patched. The SDK's
+raw finish information is retained through saved-response recovery.
+
+JSON 2.21.2 is the verified minimum for the strict decoding flags and deterministic
+schema serialization; the minimum dependency CI pins JSON 2.21.2 and RubyLLM 2.0.0
+alongside the existing minimum HTTP dependencies. Unknown SDK or parser faults
+remain failures, not poor-quality Generation results.
+
+## Failure and persistence
+
+`Agent::OutputError < Phronomy::Error` exposes execution_id, schema_digest, reason,
+violations and raw_output. Violations contain pointers/keywords without embedding
+model text. Raw text is explicitly available for controlled diagnostics; generic
+error messages do not interpolate it.
+
+| Code | Reasons |
+| --- | --- |
+| agent.output_invalid | invalid_json, schema_mismatch, missing_output |
+| agent.output_refused | model_refusal |
+| agent.output_incomplete | length, content_filter, unknown_finish_reason |
+
+Agent owns error translation. Parser invalid_json/schema_mismatch become OutputError
+with the original cause. A saved error is restored by its explicit owner codec;
+no arbitrary class name is constantized. Other transport, cancellation, Tool and
+internal failures keep their existing behavior. Output failure never triggers an
+automatic regeneration or replay of a completed Tool operation.
+
+Execution metadata stores `output_contract` version 1, schema_ref and schema_digest
+at admission. Digest is SHA-256 of UTF-8 JSON generated with recursively sorted keys
+(JSON 2.21.2 `sort_keys: true`); the exact same representation is saved in ContentStore.
+This format preserves arbitrary JSON integers and finite floats, including -0.0,
+without applying the narrower Common canonical-domain number rules. Each Context
+Manifest retains response_schema_ref, including budget projection and recovery.
+New executions may choose another schema; existing executions cannot replace their
+schema on resume/approval or by reusing a reserved ID with a different digest.
+Generic config/provider schema overrides are rejected.
+
+Structured success stores JSON result plus raw_output_ref and result_format=json.
+Old records without output_contract remain facts from a free-text execution; no
+schema is added retroactively. The execution codec stays at 0.2: its extensible
+metadata contains the explicitly versioned output contract. Unknown output-contract
+versions or digest mismatch fail closed. Saved LLM responses include finish_reason,
+refusal and metadata; missing finish evidence is unknown, never assumed normal.
+Fresh-runtime and new SQL connection-pool tests verify success, failure and approval
+continuation without replay of confirmed LLM/Tool work. This is a durable-facts
+claim, not an external side-effect exactly-once guarantee.
+
+## Generation evaluation
+
+C03 specifies the fixed protocol: draft answer/string, confidence/number in 0..1,
+citations/array; review approved/boolean, score/number in 0..1, feedback/string.
+All outer fields are required and additional properties are forbidden. Default
+citation objects require source and excerpt strings. `citation_schema:` customizes
+the citation object only; local references are rebased when embedded, without
+rewriting const/enum data. Generic validation remains with Agent/C17.
+
+The old draft_parser/review_parser arguments, DefaultParser, ParseError fallback,
+score clamping and Generation parser composition wiring are removed. C03 receives
+validated String-key values and performs domain evaluation only. Invalid output
+returns `Result` with termination_reason=output_failed, interrupted_phase, failure,
+confidence=nil and review_approved=nil. Failed draft clears any previous answer;
+failed review retains the current valid draft. iterations counts successful drafts.
+A valid score of zero can still satisfy a zero threshold; invalid data cannot.
+Normal low-quality output follows the configured evaluation loop as before.
+
+`Result#failure` is nil except for output_failed, where it carries the owned error
+diagnostic (without raw_output). Hash/JSON round trips, equality, hashing and freeze
+include it. `Result.from_h` requires every new field; migrate old saved Result JSON
+explicitly with `scripts/migrate_generator_verifier_result.rb OLD.json NEW.json`.
+The script adds failure=nil, validates the result and creates a new file. It does
+not overwrite the source or silently alter invalid data. `raise_if_unaccepted`
+retains the Result and the original OutputError cause in the same process.
+
+## Symmetric lifetime rules
+
+`Agent.open_scope` and `GeneratorVerifier.open` wait exactly once when the direct
+block return is a TaskResult. They then attempt all releases. Other values, arrays
+and nested Tasks are not recursively awaited. Failure/cancellation is re-raised
+with the same identity if cleanup succeeds. Double failure retains primary_error,
+all cleanup failures, the scope/pipeline recovery handle and the primary cause.
+`result` contains only a resolved successful value, never a failed Task.
+
+`Scope#release!` and GeneratorVerifier release retain failed owners for retry and
+remove successful ones. Return true on complete release, false after release.
+Partial release rejects new work/acquisition. Concurrent Scope release raises
+agent.scope_busy; interruption of a releasing call leaves a retryable failed state.
+Materialization receipts are drained to physical completion before release.
+Neither API implicitly cancels work, answers approval, deletes saved data or
+closes the application Store. The application decides how unfinished work becomes
+safe before retrying through the cleanup error's scope/pipeline handle.
+
+## Dependencies and implementation units
+
+- Remove C03 Generation → C17 OutputParser; C03 continues to use public C04 Agent,
+  C02 Workflow and C13 Execution contracts.
+- Add C04 Agent → C17 OutputParser as a default implementation composed at boot.
+  C04 owns the output promise and error; C17 owns syntax/schema interpretation.
+- C09 transports schema/final-response facts and remains independent of C17/C03.
+- No new Storage, Engine or Runtime-private dependency from Generation is added.
+
+The Contract concept/foundation SVGs reflect these two edges. Generation → Agent
+must retain its existing route above OutputParser. Repository source diagrams are
+regenerated by the Architecture tool; conceptual target diagrams remain distinct
+from the complete source graph.

data/docs/architecture/tracing.md

@@ -162,9 +162,9 @@ This guarantee is specific to Framework automatic instrumentation. It does not
 redefine the behavior of Application code that directly calls the public
 `Tracing::Base#trace` template method.
 
-## 10. TokenUsage
+## 10. Observed token counts
 
-`Phronomy::LLMAdapter::TokenUsage` has four fields:
+Tracing receives a plain `Hash[Symbol, Integer?]` in `usage:`. Supported keys are:
 
 ```text
 input
@@ -173,8 +173,26 @@ cached
 cache_creation
 ```
 
-A backend may export the subset its telemetry schema supports. The TokenUsage
-value object and each backend's wire representation are separate contracts.
+A backend may export the subset its telemetry schema supports. Missing/unknown
+counts remain nil and zero remains a measurement. Tracing does not accept or
+interpret a domain-specific usage object. The LLM domain retains ownership of
+its immutable usage value and aggregation rules; its caller projects the value
+with `to_h` before sending it to Tracing. Agent owns that projection for both
+`llm.call` and `agent.execution`. Arbitrary Workflow/Tool results are not inspected
+for a `usage` field by Tracing.
+
+For manual tracing, change `[result, usage]` to `[result, usage&.to_h]` when the
+second value is a domain object. Custom exporters read `usage[:input]` and
+`usage[:output]` instead of calling methods on the domain object. No compatibility
+conversion inside Tracing is retained: it would preserve the dependency being
+removed. The `usage:` keyword, span lifecycle and external telemetry field names
+are unchanged.
+
+The internal automatic task observer accepts an owner-supplied projection. A
+failed projection is diagnostic-only: it records no usage and does not change
+the operation result or prevent the span from finishing. Tracing has no static
+dependency on LLMAdapter. This does not assign LLM retry policy to Tracing or to
+the common LLM contract.
 
 ## 11. Backend notes
 

data/docs/architecture/transport-error-boundaries.md

@@ -0,0 +1,103 @@
+# RubyLLM transport error boundaries
+
+## Purpose and ownership
+
+Applications need to handle a failed provider communication through Phronomy's
+public API without knowing the HTTP client hidden behind the selected backend.
+LLM generation and embedding are separate contracts, so each retains its own
+existing `TransportError`. The concrete RubyLLM backends translate identifiable
+communication failures; Agent, Generation and Execution propagate that result.
+
+This change adds no public class, parameter, failure code, cross-contract edge,
+shared error translator or retry mechanism. Faraday references remain in the two
+concrete backends. The public RBS shape is unchanged.
+
+## Mapping and exclusions
+
+| Failure at the RubyLLM boundary | LLM complete/stream | Embeddings |
+| --- | --- | --- |
+| `Faraday::TimeoutError` | `LLMAdapter::TransportError` | `Embeddings::TransportError` |
+| `Faraday::ConnectionFailed` | `LLMAdapter::TransportError` | `Embeddings::TransportError` |
+| Existing RubyLLM errors | Existing authentication/rate-limit/context/transport classifications | Existing authentication/rate-limit/transport classifications |
+| Application streaming callback, including either Faraday class above | Original exception identity | Not applicable |
+| Cancellation, execution deadline, arbitrary I/O, programming failure or unrecognized Faraday error | Original exception identity | Original exception identity |
+
+The top-level mapped exception preserves the original message and its SDK/HTTP
+exception as `cause`. That exception's network cause is retained, for example:
+`LLMAdapter::TransportError -> Faraday::TimeoutError -> Net::ReadTimeout`.
+No classification is inferred from an exception's message or nested cause.
+The explicitly selected LM Studio backend additionally decodes the HTTP response
+body at the SDK boundary using a narrow provider-response mapping; see
+[LM Studio output failures](lm-studio-output-failures.md). This is not a generic
+exception-message or cause-chain heuristic, and the default RubyLLM mapping below
+is unchanged.
+Generic `Faraday::Error`, `Faraday::SSLError`, raw `IOError` and system errors are
+not added to this mapping. Future additions require evidence and an explicit
+category decision rather than a blanket rescue.
+
+The LLM backend's callback identity check runs before provider classification.
+An application callback throwing `Faraday::TimeoutError` therefore remains the
+same object. A provider timeout after a delivered chunk is a transport failure;
+the already delivered chunk is not withdrawn, replayed or turned into success.
+
+## Application code before and after
+
+Before, handling a provider timeout required knowledge of the backend's client:
+
+```ruby
+begin
+  response = adapter.complete(request)
+rescue Phronomy::LLMAdapter::TransportError,
+       Faraday::TimeoutError, Faraday::ConnectionFailed => error
+  warn "Provider communication failed: #{error.message}"
+end
+```
+
+After, the same communication categories are handled through the public owner:
+
+```ruby
+begin
+  response = adapter.complete(request)
+rescue Phronomy::LLMAdapter::TransportError => error
+  warn "Provider communication failed: #{error.message}"
+end
+```
+
+Embeddings applications use `Phronomy::Embeddings::TransportError` in the same
+way. Applications may inspect `cause` for diagnostics, but ordinary transport
+handling does not need a Faraday dependency. Existing specialized errors remain
+available for applications that distinguish authentication or rate limiting.
+
+## Retry, interruption and lifetime
+
+The accepted [transport-policy ADR](../decisions/011-delegate-transport-policy-to-adapters.md)
+continues to apply. RubyLLM owns its configured HTTP retries. Phronomy translates
+the failure reaching its boundary and does not replay the LLM operation, Agent
+invocation or Tool work. A transport classification does not assert that no
+output or external effect occurred, and does not authorize a retry.
+
+An execution deadline and an HTTP timeout remain different failures. This change
+does not force worker threads to stop, alter cancellation, or make an active
+Agent safe to unload. Once an ordinary provider failure has settled and its
+physical work has finished, the existing lifetime APIs can release its owners.
+
+The old Faraday 2.1.0 / faraday-net_http 2.1.0 streaming path lost HTTP status and
+caused RubyLLM to retry a schema/Tool rejection as a synthetic ServerError.
+The supported floors are now Faraday 2.14.4 / faraday-net_http 3.4.4. Real HTTP
+tests verify the original status and request count with SDK retries enabled.
+The obsolete ServerError-to-schema-rejection fallback is removed: an actual 500
+remains a server failure even when its text resembles a known 400 rejection.
+Configured SDK retries for 429/500 remain intact; no global retry switch or
+SDK monkey patch is introduced.
+
+## Verification
+
+Unit contracts cover both mapped types across complete, stream and embed,
+identity exclusions, same-class callback failures and failure after partial
+output. Loopback HTTP tests exercise the real RubyLLM/Faraday stack for timeout,
+connection loss, partial streaming with SDK retries enabled, callback identity,
+and GeneratorVerifier propagation/release. The minimum HTTP CI job runs these
+contracts too. Test-only shortened timeouts do not change production settings.
+
+These tests do not certify live model answer quality, schema/Tool combination
+support, or the root cause of the earlier unreproduced LM Studio wait.

data/docs/architecture/trust-acceptance-followup.md

@@ -0,0 +1,87 @@
+# Trust pipeline acceptance follow-up
+
+## Purpose and responsibility
+
+Communication integrity, schema validity and business truth are different
+promises. Successful HTTP and valid JSON cannot establish faithful extraction.
+
+| Concern | Owner | Change |
+| --- | --- | --- |
+| HTTP status and configured retries | HTTP stack / concrete RubyLLM backend | Require a verified stack that preserves streaming status |
+| Schema-valid terminal values | Agent, using OutputParser | Existing guarantee retained |
+| Evaluation criteria and result meaning | GeneratorVerifier | Existing protocol retained |
+| Exact invoice extraction | Application / acceptance oracle | Reject incorrect values explicitly |
+| Approval decision and Tool effects | Application decision, Agent execution, Generation routing | Observe notification, decision, effects and release |
+| Unexplained wait | Diagnostic runner plus server logs | Record payload, settings, attempts and periodic thread stacks |
+
+Contract owners, their dependencies, Engine and Execution are unchanged.
+No SDK monkey patch, extra retry loop, output repair or schema downgrade is added.
+
+## HTTP dependency correction
+
+Faraday 2.1.0 with faraday-net_http 2.1.0 did not pass the response environment to
+streaming callbacks. RubyLLM 2.0.0 could interpret a JSON 400 as a synthetic 500.
+401 and 429 could also lose their identity. The ServerError fallback additionally
+misclassified an actual 500 whose text matched the known schema rejection.
+
+Supported floors are now Faraday 2.14.4 and faraday-net_http 3.4.4, the pair
+already verified on the normal path. Both are explicit in the gemspec: raising
+Faraday alone does not exclude older Net::HTTP adapters. CI pins and checks both,
+with the existing minimum RubyLLM, MCP and JSON versions. These are verified
+support floors, not claims about the earliest upstream fix. Custom Faraday
+adapters need their own streaming/status compatibility assessment.
+
+The obsolete ServerError fallback is removed. Only a real BadRequestError with
+the known body becomes StructuredOutputUnsupportedError. Actual 500 responses
+retain the SDK server-error cause. Configured SDK retries for 429/500 remain;
+a 400 rejection is one HTTP attempt even with three retries configured.
+Partial-stream replay and callback identity regressions remain in place.
+
+Before and after, application handling uses the same public API:
+
+```ruby
+rescue Phronomy::LLMAdapter::StructuredOutputUnsupportedError => error
+  warn error.cause.class
+```
+
+Before, the old stack could issue four requests and expose a synthetic ServerError
+for HTTP 400. After, the cause is BadRequestError and that rejection is not
+retried as a transient server failure.
+
+## Content fidelity and acceptance
+
+The invoice demo keeps its general string/number schema and asks the model to
+preserve identifier characters. After Agent release, an independent oracle checks
+the fixed fixture. Incorrect values exit 1; they are never replaced or retried.
+This is fixture acceptance, not a general invoice validator or Agent responsibility.
+
+Before, INV-2026-01 could print and exit successfully for source INV-2026-001.
+After, it is a fidelity failure, while schema validation remains correctly
+successful. One correct response does not establish general model accuracy.
+
+The examples runner checks invoice, accepted, iteration_limit and approval
+yes/no/cancel independently. Approval requires a notification and the expected
+Tool effects. A schema/Tool rejection is blocked, not successful approval.
+Yes checks approval and valid completion; accepted is a separate test because
+Tool approval does not guarantee that evaluation criteria will be satisfied.
+
+## Wait diagnosis and limits
+
+The opt-in runner observes the pinned SDK without replacing the provider or
+changing timeout/retry settings. It records UTC times, request payloads/hashes,
+settings, physical HTTP attempts, results, exception causes, releases and periodic
+Ruby thread stacks. Observer failures invalidate the report and do not replace
+the application exception. Signals wrapped by cleanup errors remain interrupted.
+
+Observation uses diagnostic-only SDK method bindings and must be reviewed when
+the SDK changes. Reports contain prompts/responses. Sampling and file writes add
+overhead; this runner is not a performance benchmark.
+
+Historical LM Studio logs cannot be reconstructed. Match the saved review payload
+and UTC times with server logs; use future wait stacks to identify pending
+HTTP/SDK/framework operations before assigning a cause. A later fast response
+does not resolve the earlier wait.
+
+Controlled HTTP fixtures prove framework and observation behavior, not live
+model accuracy or server support for schema plus Tools. Live acceptance still
+requires a suitable model/server environment and recorded server version.