phronomy 0.28.0 → 0.30.0

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.

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