phronomy 0.30.1 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 077db55116aa3b2b1deeeabef69b46b5481c72f1636aa4c623ad8b843d20ef38
-  data.tar.gz: 07bbf1214b2aaaf6df1403c69ff8e9f7a7bc4bc8dac63ec4a7a1b11955c0a014
+  metadata.gz: e7eb1f72acaa35f02d5f848dac344ea971e6ef190544d2b200fe367409e48e92
+  data.tar.gz: 26b2de048b30845bdbf973a5e26a6d5fa4b734295d31b81cec2530e9dd896dc8
 SHA512:
-  metadata.gz: a28ae543ff3826e964cd235580a01175446187546f5f2c94ed34bf12cfd967337df9673654b3029d9173f99479cc32ef966f5bac71db2918cd0265402860e124
-  data.tar.gz: ca6dbea79bc432cb1802dbec83cae8b427011b6782f11cfce02fa30ec5b5003439e6b4e6fedd48b6a589ba6b9374075491ae796549dabe41746f20c43f2ee143
+  metadata.gz: eaf92481864d37b545ccf7507541fbd64777eb6ff6369e2f8a674f31341bc2ec439883dfa2964d410c1becc2adc92c2794c9a7a2e6a7a2e5050a78e2ae4fa181
+  data.tar.gz: 6ca6f91cc3bf270a2694cb5a8a194cc1f4fe8270440ada751a4082f0ae27489c0798743a351d8850e1fbf4e81eb0aac207bee563995e8aa821d2008b2b6916e2

data/CHANGELOG.md

@@ -12,6 +12,69 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-10-25
+
+### Added
+
+- Add explicit Agent `schema_delivery: :native | :none` across execution entry
+  points and GeneratorVerifier. Local structured-output validation is identical
+  in both modes; existing calls retain native delivery.
+- Add `Agent#transcript_messages` and its async counterpart to read immutable
+  Message values without application knowledge of Journal storage.
+- Add `Tools::Agent::CleanupError` (`tool.agent_cleanup_failed`) with the child
+  Agent, successful result and primary/cleanup failures needed to diagnose failed
+  release and retry `child_agent.unload_async` without repeating the invocation.
+
+### Persistence
+
+- Save new output contracts as version 2 with the delivery choice and retain their
+  schemas even when no schema is sent. These executions use envelope 0.3, rejected
+  by older readers. Existing version-1 contracts remain native and readable.
+
+### Fixed
+
+- Preserve streamed refusal facts even when native schema delivery is omitted.
+- Release the one-shot Agent owned by `Agent.run_once` through `Agent.open_scope`.
+  Preserve the invocation value or original exception when release succeeds;
+  report unsafe or failed release through `Agent::ScopeCleanupError` with the
+  result, primary error and scope needed for a release-only retry.
+- Give each Agent-backed Tool call explicit ownership of its fresh child and
+  ephemeral Store. Complete release after logical and physical invocation
+  completion, without occupying a worker merely to wait. Preserve approval,
+  cancellation, independent leases, retention and recovery restrictions.
+- Acknowledge terminal execution waiters before publishing their result while
+  retaining each operation's physical lease until its work actually finishes.
+- Stop completed Agent Tool handles from retaining released children through
+  generated callback owners, temporary state-machine tracker context or completed
+  `ExecutionChange` wiring. Clear execution-only references after commit and any
+  ambiguous-outcome readback, including failure paths. Keep single-use guards,
+  saved results, session ownership and recovery behavior intact.
+
+### Changed
+
+- Both synchronous and asynchronous Agent Tool calls now use the child's
+  `invoke_async`. An override of only `invoke` no longer changes synchronous
+  Agent Tool execution; update custom child subclasses accordingly.
+- Agent Tool cleanup failures are surfaced and diagnosed, including after an
+  outer observer cancels. A general Tool error-suppression policy cannot hide
+  failed child release.
+
+### Verification and migration
+
+- Read the [0.31 migration notes](docs/migrations/0.31.md) before upgrading stored
+  executions or custom Agent Tool subclasses. Deploy readers that support
+  AgentExecution 0.3 before writing new structured executions; older readers
+  cannot read these records, including completed executions. Existing 0.2 records
+  and version-1 native output contracts remain readable without a read-time rewrite.
+- LM Studio/gpt-oss PEG output parsing remains an unresolved external limitation.
+  Existing known-error identification and bounded retry are not a root-cause fix.
+  The DX1/DX2 live normal path, streaming, Tool use and history restoration remain
+  unverified in that environment. This release relies on source review, offline
+  regressions and CI; it does not claim completion of live LLM acceptance.
+  Historical initial success and bounded retry/stop evidence retain their limited
+  scope; retry recovery and recurrence resolution remain unverified.
+
+
 ## [0.30.1] - 2026-10-24
 
 ### Documentation
@@ -40,6 +103,8 @@ Runtime behavior, public APIs and dependency requirements match 0.30.0.
 
 ### Changed
 
+- Generate architecture SVG metadata in English, including repeated formatting.
+
 - 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

data/README.md

@@ -37,14 +37,18 @@ tracking `main` directly.
 
 See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
 
-The following application APIs are available as Beta in v0.30.0:
+The following table describes the application APIs available in v0.31.0.
+Review the [0.31 migration notes](docs/migrations/0.31.md) before upgrading
+persistent applications or custom Agent Tool subclasses.
 
 | 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) |
+| Agent `output_schema:`, `schema_delivery:`, `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) |
+| Agent `transcript_messages` / `transcript_messages_async` | Beta | Read immutable conversation Message values with the same restoration rules as execution results; [reading conversation state](docs/getting-started.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) |
+| `Tools::Agent::CleanupError` | Beta | Added in v0.31.0. Preserves the child, result and failure causes when safe release fails; retry `child_agent.unload_async` for release only; [contract](docs/architecture/agent-tool-child-lifetime.md) |
 | `Workflow::Builder#task_state` and `WorkflowTaskResumeError` | Beta | State-entry-scoped Task completion, live cancellation and explicit restart rejection; [contract](docs/architecture/dx05-workflow-task-state.md) |
 | `Phronomy::Integrations::OrderedEventDelivery` | Beta | Optional ordered delivery with bounded admission and explicit drain lifetime; [usage](docs/ordered-event-delivery.md) |
 | `Phronomy::Error#code` and error constructor `code:` | Beta | Optional reason codes and bounded causes retained in saved failure diagnostics; [meaning and compatibility](docs/architecture/error-api-review.md) |
@@ -189,6 +193,7 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 - [Persistence failure contract migration](docs/migrations/persistence-failure-contracts.md) — domain rescue clauses and unchanged raw backend errors.
 - [0.19 unified Persistence migration](docs/migrations/0.19.md).
 - [0.22 semantic Multi-Agent Handoff migration](docs/migrations/0.22.md).
+- [0.31 persistence and Agent lifetime migration](docs/migrations/0.31.md).
 - [Architecture Decision Records](docs/decisions/) — design rationale and superseding decisions.
 - [CHANGELOG](CHANGELOG.md) — current development and recent release history.
 - [Changelog archive: 0.14.0 and earlier](docs/changelog/0.14-and-earlier.md).

data/docs/architecture/agent-tool-child-lifetime.md

@@ -0,0 +1,141 @@
+# Agent Tool child lifetime
+
+`Tools::Agent.from_agent` owns one fresh Agent and ephemeral Store per call.
+The Tool releases its private live child after the invocation and its physical
+work finish. Ordinary application-owned Agents and durable MultiAgent children
+retain their own explicit lifetime and recovery policies.
+
+## Public behavior
+
+`from_agent`, `call`, `call_async` and `execute` keep their arguments. Successful
+output remains `result[:output].to_s`, including the empty String for nil. Tool
+validation, cancellation-token precedence, error policy, truncation and configured
+result-transform order remain in their existing owners.
+
+The synchronous `execute` now waits for the same internal asynchronous operation
+used by `call_async`. Both invoke the child's `invoke_async` implementation.
+An application override of only `invoke` no longer changes the synchronous Tool
+path; there is no legacy dispatch branch. Synchronous EventLoop entry is rejected
+before creating a Store or child.
+
+Normal Tool completion includes release. No OffloadPool worker or new Thread is
+used merely to wait for the child or its release. The existing Agent release can
+perform its ordinary asynchronous persistence checks. Records are not purged,
+and unrelated Agents or shared stores are not shut down.
+
+## Cancellation and approval
+
+Logical result settlement does not prove that physical work has ended. The
+operation keeps ownership until both source boundaries are complete, then calls
+the existing `unload_async`. Cancelling an observation handle does not cancel
+this finalization or silently release an active child. Use the accepted
+CancellationToken to request operation-wide cancellation.
+
+Pending approval is not terminal. This Tool neither auto-approves nor adds a
+child-event forwarding API. A child requiring external approval still needs an
+application-defined way to deliver that approval. Active work, other accepted
+operations, retention and unresolved recovery continue to prevent release.
+
+When several Agent calls observe the same terminal execution, C04 acknowledges
+all of those finished operations before publishing any logical result. Otherwise
+the first result callback could request release before a sibling approval waiter
+has acknowledged completion. Each OperationResult still waits for its own tracked
+physical work. Independent operations and synchronous caller leases remain live;
+they are not force-released by this batching.
+
+## Cleanup failure
+
+On successful cleanup, the operation preserves its output or original exception.
+Ordinary Tool error policy is applied afterward. A cleanup failure instead raises
+`Tools::Agent::CleanupError`, a `ToolError` with code
+`tool.agent_cleanup_failed`, even when the Tool suppresses ordinary failures.
+
+| Reader | Meaning |
+| --- | --- |
+| `child_agent` | The exact child instance whose release failed |
+| `agent_id` | That child's identity |
+| `result` | The successful String before Tool truncation, or nil |
+| `primary_error` | Invocation or conversion failure, when present |
+| `cleanup_error` | Release failure |
+| `cause` | The primary error when present, otherwise the cleanup error |
+
+The application may retry `error.child_agent.unload_async` when the release
+condition has been resolved. This retries release only: it never invokes the
+Agent, model or Tool again. The error and live child reference are process-local;
+persisted error diagnostics do not reconstruct an owner or retry capability.
+
+Every cleanup failure is also reported with its child identity, stable code and
+both available failure diagnostics. This includes failures after an outer
+observer has already cancelled its handle. The settled observer is not overwritten.
+The owner remains registered for inspection through the existing Agent API.
+Diagnostic failures do not replace the operation error or repeat work.
+
+## Responsibility boundaries
+
+| Owner | Responsibility |
+| --- | --- |
+| I04, concrete Agent Tool | Fresh child acquisition, invocation, output conversion, release request and child-specific failure information |
+| C04, Agent | Admission, physical-operation leases, approval, recovery, retention, unload safety and terminal waiter acknowledgment |
+| C06, Tool | Input validation, general error policy, truncation and result transformations |
+| C13, Execution | Neutral logical/physical completion and asynchronous finalization composition |
+
+The private `AsyncOperation.finalize` captures startup failure, observes a
+TaskResult's logical and physical completion, starts one supplied cleanup
+operation and observes its completion. The owner supplies error combination.
+It is independent of application Execution cancellation and contains no Agent,
+Store, Tool or provider policy. A callback-only source is not accepted by this
+private finalization API; the start and cleanup functions must return TaskResults.
+
+This does not add a public finally, async scope or one-shot Agent API. The
+concrete Tool does not regain a dependency on the application `run_once`
+composition, and does not manually settle TaskResults. Agent release decisions
+are not moved into Execution or Engine.
+
+## Runtime reference lifetime
+
+Agent entry actions resolve their owner from the invocation being processed.
+They do not curry a live Agent into the generated state-machine class. This
+prevents VM method caches for generated callbacks from extending Agent lifetime.
+
+FSMSession owns its context between events. The state-machine tracker receives
+that context while an event is dispatched, then drops its temporary reference
+when dispatch returns, including on errors. Later events rebind the same live
+session context. This does not clear the session's context, end pending work,
+change approval handling, or relax Agent unload admission.
+
+For example, retaining a completed Tool handle must not retain the child through
+either generated callbacks or a completed state-machine transition. Ruby 3.2.3
+can retain those execution objects through method caches after the logical
+operation ends. Separating their temporary references from session ownership
+allows the released child to be collected without changing the Ruby or
+state_machines dependency versions.
+
+Completed synchronous `ExecutionChange` objects can also remain reachable from
+an idle worker's Fiber/stack, including on the Ubuntu build of Ruby 3.2.3. After
+commit and any ambiguous-outcome readback finish, the change drops its live Agent,
+write callback and participant references. It keeps its result and descriptive
+data. This cleanup runs after success or failure, never before the participant's
+commit, evidence collection or recovery guards have finished. A completed change
+remains single-use; it does not grant a new opportunity to commit or replay work.
+
+These changes stay inside Agent execution/participation and Engine dispatch
+lifetime; they introduce no new Contract dependency or public API. In particular,
+OffloadPool does not acquire Agent-specific cleanup policy, replace worker
+threads, or create a new Fiber to make collection happen.
+
+## Verification
+
+Offline tests use real Agent operations and a fixed local LLMAdapter. They cover
+sync/async success and failure, startup and conversion errors, repeated calls,
+single-worker parent Tool dispatch, approval, independent leases, parallel
+children, observer and token cancellation, cleanup failure and retry, shutdown,
+result transforms and collectability while one or several completed handles
+remain live. The original single-child GC assertion is retained unchanged.
+Participation tests retain completed changes while checking collection of their
+execution-only wiring after success, rollback and lost commit response. The
+last case also verifies that readback runs once and returns the committed result.
+Neutral completion tests exercise both boundary orders, duplicate/concurrent
+notifications, cancellation, startup/cleanup errors and invalid handles.
+
+These tests do not establish real-provider availability or resolve LM Studio's
+separate PEG output-parse failure.

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

@@ -113,8 +113,10 @@ removal is performed.
   blocks release.
 
 For notifications, finish child processing, drain notifications, then exit the
-Agent scope. `run_once` retains its existing Store and lifetime behavior; merely
-calling it does not opt into scope cleanup.
+Agent scope. `run_once` owns a fresh ephemeral Store and an Agent scope. It releases
+the Agent before returning or propagating an invocation failure, using the same
+release and cleanup-error rules. Use an explicit scope when ownership must extend
+past the invocation, for example until final notification delivery has drained.
 
 This is P5 (core). P6 migrates application examples and performs cross-repository
 acceptance against the published or pinned candidate core.

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

@@ -8,7 +8,11 @@ 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.
+`start_reserved_async` accept `output_schema: nil` and `schema_delivery: nil`.
+`run_once` forwards both options. With a schema, omitted/nil delivery means
+`:native`; explicit `:native` and `:none` are supported. A non-nil delivery without
+a schema, or any other value, raises ArgumentError before admission. The same
+keywords and final-output semantics apply to sync/async and invoke/stream.
 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.
@@ -45,9 +49,21 @@ values and String/Symbol keys, snapshots recursively, and rejects duplicate norm
 keys, Ruby objects and cycles. Generic schema interpretation belongs to C17, not
 Tool::Schema, Agent's caller or Generation.
 
-## Native transport and completion facts
+## Schema delivery and completion facts
 
-C09 `LLMAdapter::Request#response_schema` carries the immutable schema; each model
+`:native` sends the declared schema to the provider. `:none` omits native schema
+configuration on every turn, including Tool follow-ups, but retains the same
+strict local validation, completion checks, output filters, frozen values and
+OutputError reasons. It does not send JSON mode, rewrite prompts, infer behavior
+from provider/model names, fall back after rejection or regenerate malformed
+output. Applications must already ask for the declared JSON shape in their
+instructions. Tools and their authorization rules remain unchanged.
+
+Use `schema_delivery: :none` explicitly where native schema delivery cannot be
+combined with the application's Tools. This does not repair LM Studio PEG errors:
+a provider failure before a usable response remains a provider failure.
+
+With `:native`, 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
@@ -77,7 +93,7 @@ unknown), refusal and raw_finish_reason metadata. Only normal final completion c
 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 facts on every stream, independently of native schema delivery. 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
@@ -104,21 +120,28 @@ 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
+New structured executions store `output_contract` version 2, schema_ref,
+schema_digest and schema_delivery (`"native"` or `"none"`) 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.
+Manifest carries response_schema_ref only for native delivery. The output
+contract always keeps schema_ref, including with `:none`, so local validation
+survives recovery. The digest identifies the schema alone; exact execution identity
+also compares delivery. Resume/approval restore the saved choice, and a reserved
+ID cannot be reused with a different schema or delivery. 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,
+schema is added retroactively. Existing output_contract version 1 is read as
+native delivery and is not rewritten merely by reading. Version-2 contracts use
+AgentExecution envelope 0.3; old/freeform executions retain envelope 0.2. New
+readers accept both explicitly. Older readers reject envelope 0.3, including for
+completed executions, instead of silently losing delivery policy. Deploy compatible
+readers before writing new structured executions; do not downgrade a store that
+contains 0.3 records to older readers. Unknown versions and 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
@@ -126,6 +149,11 @@ claim, not an external side-effect exactly-once guarantee.
 
 ## Generation evaluation
 
+`GeneratorVerifier.new` and `.open` accept `schema_delivery: :native` (default) or
+`:none`. One choice applies to both draft and review operations. Their independent
+schemas and C03 evaluation policy remain unchanged; no role-specific flags or
+automatic fallback are introduced.
+
 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
@@ -168,6 +196,38 @@ 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.
 
+## Single-invocation ownership
+
+`Agent.run_once(definition:, input:, context: nil, knowledge: [], on_event: nil,
+**invoke_options, &event_block)` creates a fresh ephemeral Store and owns one
+Agent through `Agent.open_scope`. The definition must be an `Agent::Base`
+subclass. It forwards the input and invocation options, including the output
+schema and delivery selection, and releases the live Agent before returning.
+The application-level Store configuration is not used or changed.
+
+Successful cleanup preserves the invocation value or the identical invocation
+exception. A cleanup failure raises `Agent::ScopeCleanupError`: `result` retains
+a successful value, `primary_error` retains an invocation failure, `failures`
+identifies unreleased owners, and `scope.release!` can retry release. It does not
+repeat the invocation, model request or Tool work. Release does not purge records,
+close shared storage or shut down Runtime. No keep-alive option or legacy path
+is provided; use `create`/`load` or an explicit scope for a reusable Agent.
+
+The synchronous call cannot run on EventLoop. It rejects that entry before
+creating its Store or Agent. Supplying both `on_event:` and a listener block is
+also rejected before acquisition. The existing listener-error policy is preserved.
+
+Approval waits are not completion. The Agent remains owned while the invocation
+waits; the application still decides approval through the existing API. Use
+`approve_async` when another operation is already waiting for the same execution.
+A concurrent synchronous approval or other accepted operation can still own a
+lease when the invocation returns. In that case cleanup reports the busy owner
+through `ScopeCleanupError`; finish the other operation before retrying release.
+Logical cancellation likewise cannot authorize release of physically active work.
+The convenience API neither answers approval nor cancels or waits for unrelated
+work to make cleanup succeed. Applications needing notifications or other work
+after the invocation should express that whole lifetime with `open_scope`.
+
 ## Dependencies and implementation units
 
 - Remove C03 Generation → C17 OutputParser; C03 continues to use public C04 Agent,

data/docs/decisions/044-agent-default-and-one-shot-composition.md

@@ -5,6 +5,11 @@
 **Refines**: [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md)
 and [040-configuration-default-composition](040-configuration-default-composition.md)
 
+The original lifetime-preservation decision below is historical. The current
+`run_once` contract owns a scope and releases its Agent; see
+[single-invocation ownership](../architecture/structured-output-and-scope.md#single-invocation-ownership).
+The composition placement and default-factory boundary remain in force.
+
 ## Problem
 
 `Agent::Base` selected the concrete default with `Persistence.in_memory`.

data/docs/getting-started.md

@@ -137,6 +137,26 @@ mutable Agent/Execution/Journal state before every LLM or Tool step. A conflicti
 external durable write is surfaced as `Phronomy::Persistence::StateConflictError` rather than
 silently merged into the live instance.
 
+Read persisted conversation values without interpreting Journal storage:
+
+```ruby
+messages = agent.transcript_messages
+messages.each { |message| puts "#{message.role}: #{message.content}" }
+```
+
+`transcript_messages_async` returns a TaskResult with the same frozen array of
+`LLMAdapter::Message` values. For the same durable root, these match
+`result[:messages]`, including Tool calls, Tool results, non-text content and
+opaque metadata. The operation selects root/generation and Journal records in one
+transaction, then restores immutable content off EventLoop. It holds Agent
+ownership until physical completion, including after logical cancellation.
+The synchronous method refuses to wait on EventLoop. Content and integrity
+failures propagate; an unreadable transcript is not an empty conversation.
+
+`agent.transcript` remains a JournalRecord view. Knowledge is excluded from the
+conversation. The application still owns authorization, role filtering and
+presentation; reading invokes no LLM or Tool and changes no durable state.
+
 The active transcript and Knowledge views can be advanced independently without
 deleting the append-only canonical Journal:
 
@@ -379,6 +399,12 @@ Agent-backed Tools return control to EventLoop while the child lifecycle is
 waiting. They do not occupy an OffloadPool worker merely to wait for a child
 Agent result.
 
+Each call owns and releases its fresh child Agent after physical work finishes.
+Normal completion includes that release; a failed release preserves the result,
+original error and child in `Tools::Agent::CleanupError`. See
+[child lifetime and cleanup](architecture/agent-tool-child-lifetime.md) for
+cancellation, approval and release-only retry rules.
+
 ## Filters
 
 Filters can transform or reject values at Agent boundaries:

data/docs/migrations/0.31.md

@@ -0,0 +1,72 @@
+# Migrating to Phronomy 0.31
+
+Phronomy 0.31 adds explicit schema delivery and durable transcript reads, and
+fixes ownership and release of one-shot and Agent Tool children. Review these
+compatibility boundaries when upgrading from 0.30.1.
+
+## Stored executions
+
+New structured executions store output-contract version 2 with `schema_delivery`
+and use AgentExecution envelope 0.3. The schema remains saved and locally
+validated even with `schema_delivery: :none`; omitting native schema delivery is
+an explicit application choice, not an automatic fallback or output repair.
+
+Deploy compatible readers before writing these records. Older readers reject
+0.3, including completed executions; do not downgrade a store containing them.
+Version 0.31 still reads envelope 0.2 and existing version-1 native output
+contracts without rewriting them merely on read. Existing free-text records do
+not acquire a schema retroactively. See the
+[structured-output persistence contract](../architecture/structured-output-and-scope.md#failure-and-persistence).
+
+## One-shot Agent ownership
+
+`Agent.run_once` owns its fresh Agent and ephemeral Store through
+`Agent.open_scope` and releases the live Agent before returning. A reusable
+Agent must instead use `create`/`load` or an explicit ownership scope.
+
+When release succeeds, the original invocation value or exception is preserved.
+Unsafe or failed release raises `Agent::ScopeCleanupError`, retaining the result,
+primary error, failed owners and scope. Resolve the release condition before
+retrying `error.scope.release!`; this does not repeat model or Tool work.
+Approval waits, physical work, independent leases, retention and recovery still
+prevent unsafe release. No records are purged and no shared Store or Runtime is
+shut down. See [single-invocation ownership](../architecture/structured-output-and-scope.md#single-invocation-ownership).
+
+## Agent-backed Tools
+
+Both synchronous `execute` and asynchronous `call_async` now invoke the child
+through `invoke_async`. A subclass that overrides only `invoke` no longer
+changes the synchronous Tool path. Move the intended customization to the
+asynchronous entry point and preserve its TaskResult contract.
+
+Each call owns its fresh child and ephemeral Store until invocation and physical
+work have finished and safe release completes. Normal return includes release;
+successful output conversion remains unchanged. Waiting does not consume an
+OffloadPool worker solely to join the child.
+
+A release failure raises `Phronomy::Tools::Agent::CleanupError` with code
+`tool.agent_cleanup_failed`. It retains `child_agent`, `agent_id`, `result`,
+`primary_error` and `cleanup_error`; the cause is the primary failure when one
+exists, otherwise the release failure. Resolve the release condition, then retry
+`error.child_agent.unload_async` for release only. These live handles are
+process-local and are not reconstructed from saved error diagnostics.
+
+Cleanup failures are also diagnosed after observer cancellation and are not
+hidden by ordinary Tool error suppression. Completed runtime wiring no longer
+retains released children through generated callbacks, temporary tracker context
+or completed participation changes. Session ownership, commit/readback ordering,
+physical leases and recovery guards remain unchanged. See the
+[Agent Tool child lifetime contract](../architecture/agent-tool-child-lifetime.md).
+
+## Live-provider limits
+
+LM Studio/gpt-oss PEG output parsing remains unresolved. Known-error
+identification and one bounded retry do not establish the root cause or prevent
+recurrence. The existing evidence distinguishes a failed call stopped after two
+POSTs from a separate application invocation that succeeded on its first POST;
+it does not show recovery by retry within one call.
+
+The DX1/DX2 normal live path, streaming, Tool use and history restoration remain
+unverified in that environment. Source review, offline tests and CI support this
+release; they do not establish live LLM acceptance. See the
+[LM Studio policy and evidence limits](../architecture/lm-studio-output-failures.md).

data/lib/phronomy/agent/async_event_api.rb

@@ -12,12 +12,12 @@ module Phronomy
     # - approval notifications share the Agent listener as :approval_required;
     # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
-      def start_reserved_async(reservation:, input:, config: {}, output_schema: nil)
+      def start_reserved_async(reservation:, input:, config: {}, output_schema: nil, schema_delivery: nil)
         __with_operation(async: true) do
           unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
             raise ArgumentError, "reservation must belong to this Agent"
           end
-          config = __invocation_config(_prepare_output_config(config, nil, output_schema))
+          config = __invocation_config(_prepare_output_config(config, nil, output_schema, schema_delivery))
           ExactExecution.start(agent: self, execution_id: reservation.execution_id, input: input,
             config: config.merge(phronomy_reservation: reservation.correlation))
         end
@@ -54,12 +54,13 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _check_event_loop_reentrancy(:invoke, :invoke_async)
           _start_agent_operation(
             input,
@@ -75,12 +76,13 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation(async: true) do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _start_agent_operation(
             input,
             config: config,
@@ -95,13 +97,14 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
           listener = _required_stream_listener!(:stream)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _check_event_loop_reentrancy(:stream, :stream_async)
           _start_agent_operation(
             input,
@@ -117,13 +120,14 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation(async: true) do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
           listener = _required_stream_listener!(:stream_async)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _start_agent_operation(
             input,
             config: config,
@@ -206,9 +210,14 @@ module Phronomy
 
       private
 
-      def _prepare_output_config(config, invocation_context, schema)
+      def _prepare_output_config(config, invocation_context, schema, schema_delivery)
         config = _prepare_invocation_config(config, invocation_context)
-        schema.nil? ? config : config.merge(phronomy_output_contract: OutputContract.new(schema))
+        if schema.nil?
+          raise ArgumentError, "schema_delivery requires output_schema" unless schema_delivery.nil?
+          return config
+        end
+        contract = OutputContract.new(schema, schema_delivery: schema_delivery.nil? ? :native : schema_delivery)
+        config.merge(phronomy_output_contract: contract)
       end
 
       def _start_agent_operation(input, config:, mode:, listener:)