phronomy 0.27.0 → 0.29.0

data/docs/migrations/r8-unit7.md

@@ -0,0 +1,31 @@
+# Migrating to r8 unit 7
+
+Apply after core b337fc77dae530269bc34d895365032873d544ad (r8 unit 6).
+Public Agent invocation, streaming, approval, cancellation and recovery signatures
+and persistence record schemas are unchanged. The current unit 6 examples need
+no source changes. Run them against the candidate using PHRONOMY_PATH and the
+correct BUNDLE_GEMFILE for each example directory.
+
+There are no compatibility aliases for removed internal APIs:
+
+| Internal use | Replacement |
+| --- | --- |
+| AgentInvocationSessionBuilder | AgentInvocation plus the owning ExecutionEnvironment.build_agent_session |
+| AgentInvocationSessionBuilder entry/prepared actions | InvocationActions |
+| ExecutionSessionRunner.new(runtime: ...) | ExecutionSessionRunner.new(environment: ...) |
+| OwnershipRegistry.for/existing_for(Runtime) | Pass an ExecutionEnvironment; EngineEnvironment adapts Runtime |
+| ExecutionReceiver subclasses initialize(event_loop:) | initialize(channel:), preserving super |
+| AgentInvocation.begin_llm_call! implicit Runtime lookup | Explicit llm_call_id from durable prepared execution |
+
+ExecutionEnvironment is a private framework connection, not an application
+configuration feature. Do not serialize environments, channels, sessions or live
+registries. The default composition is installed by requiring phronomy. State
+policy loading alone does not install a runtime. Existing persisted Agent/Tool
+identities, revisions, authorization snapshots and recovery classifications are
+retained. This change does not add support for exchanging in-flight unit 5 or
+older execution snapshots with unit 6/7 workers.
+
+Stop/drain old processes using the existing deployment procedure before replacing
+code. Deploy all internal call-site changes together. The application package
+contains a strict-base dry-run/applier, expected-tree verification, review patch,
+validation logs and rollback guidance. Run --verify before and after commit.

data/docs/migrations/r8-unit8.md

@@ -0,0 +1,33 @@
+# Migrating to r8 unit 8
+
+Apply after core a601a0654ace42640f0251b129359ca1f326e3ad (unit 7).
+This is a core-only change. The unit 6 examples at
+ed455c52018338f7c5a4c2948ae0d7db131aa090 require no source changes.
+
+Public Agent invocation/stream/approval/cancellation/recovery signatures and
+Tool#call_async(args, cancellation_token:, config:) are unchanged. Tool::Operation
+adds an explicit C06 operation entry and result transformation API; application
+Tools do not need to adopt it. The supplied submitter applies to the default
+offloaded operation only. Custom async implementations retain their existing
+execution mechanism and configuration.
+
+| Internal use | Replacement |
+| --- | --- |
+| Agent::ToolInvocationSessionBuilder.build / build_for_resume | The owning ExecutionEnvironment.build_tool_session, with resume_event/resume_phase when needed |
+| ToolInvocationSessionBuilder transition constants | Agent::ToolInvocationTransitions |
+| ToolInvocationSessionBuilder entry operations | Agent::ToolInvocationActions |
+| ToolInvocation.start_authorization/runtime: and start_execution/runtime: | Pass environment: explicitly; never reconstruct it from a new global Runtime |
+| Tool::ToolExecutor.call_async(runtime:) | Tool::Operation.call_async(submitter:) for contract consumers; default executor takes submitter: internally |
+| Agent ToolBinding's custom-async detection and mapping mechanism | Tool::Operation.with_result_transform; Agent retains filter configuration |
+
+Removed internal names have no aliases. Deploy all internal call sites together.
+Do not persist execution environments, submitters, FSM sessions or parent sinks.
+Durable IDs, record schemas, revision checks and saved approval evidence are
+unchanged. The change does not certify new in-flight cross-version compatibility.
+Use the existing stop/drain procedure before replacing running processes.
+
+The application ZIP contains strict-base --check/--apply/--verify commands,
+complete replacement files and deletions, expected-tree verification, a review
+patch, validation evidence and rollback instructions. Run --verify before and
+after commit. Verify examples with PHRONOMY_PATH pointing at the candidate and
+unset a stale BUNDLE_GEMFILE before entering each Bundler context.

data/docs/migrations/r8-unit9.md

@@ -0,0 +1,28 @@
+# R8 unit 9 migration
+
+Apply to core unit 8, commit e9f6cc16da19be82a0b7777486926ba46d070def.
+Examples source remains at unit 6, ed455c52018338f7c5a4c2948ae0d7db131aa090.
+
+No public Tool or Agent signature, stored schema, migration CLI or example source
+change is required. Existing configured filter order and repeated registrations
+are preserved. The correction removes only the extra transformation caused by
+Base's standard async-to-sync delegation under a custom async result decorator.
+
+A custom call_async using super now passes its raw delegated result through its
+own processing before the async decorator applies the configured transform.
+Code accidentally relying on the duplicate/intermediate transformation should
+express the required stages explicitly in application filter configuration.
+
+A custom call_async explicitly calling public call retains that call's filters;
+the enclosing async result decorator also retains its stage. Do not substitute
+call for super when the intent is to delegate to Base's normal async execution.
+The framework does not suppress application-authored calls or infer their intent.
+
+Private changes: Base uses Tool::Operation.synchronous_delegate; ToolExecutor
+accepts a bound synchronous_call keyword. Applications should not use these
+private bridge helpers. Custom async implementations retain their existing
+execution mechanism and keyword protocol.
+
+Use the normal process stop/drain and restart procedure. This unit does not add
+cross-version in-flight compatibility or rollback of external Tool side effects.
+See docs/architecture/r8-unit9.md for operation-boundary examples.

data/docs/migrations/storage-async-client.md

@@ -0,0 +1,103 @@
+# Storage asynchronous execution and ContentStore ownership
+
+P4 adds the public Beta `Phronomy::Storage::AsyncClient`. Synchronous storage
+backends and `Persistence#transaction` keep their existing interfaces. Backend
+authors implement no scheduler or async methods.
+
+## Public transaction API
+
+Construct `Storage::AsyncClient.new(backend: raw_backend, pool: nil)` around a
+Storage SPI 2 backend. For an existing Persistence facade, use
+`persistence.backend`. The transaction block receives a **raw Storage::View**,
+not the domain repositories yielded by `Persistence#transaction`.
+
+`transaction_async(cancellation_token: nil, timeout: nil) { |view| ... }`
+returns the pool's original TaskResult. The complete transaction runs on one
+worker, using the backend's normal connection and scope. Do not split a
+transaction across workers or wait for another TaskResult inside its block.
+Explicit synchronous `backend.transaction` calls within the block retain nested
+savepoint behavior.
+
+### Complete offline example
+
+This requires a checkout containing P4; the previously released 0.27.0 gem does
+not contain the new client. It uses only the public raw storage contract.
+
+```ruby runnable
+require "phronomy"
+require "json"
+
+resource = Phronomy::Storage::Resource.new(id: "example.notes", kind: :records)
+backend = Phronomy::Storage::Backends::InMemory.new(resources: [resource])
+client = Phronomy::Storage::AsyncClient.new(backend: backend)
+
+begin
+  record = Phronomy::Storage::DurableRecord.new(
+    record_type: "example.note", format_version: "0.1", payload: {"text" => "saved"}
+  )
+  task = client.transaction_async do |view|
+    rows = view.records(resource)
+    rows.insert(key: "note-1", revision: 1, attributes: {}, record: record)
+    rows.fetch("note-1").record.payload
+  end
+  puts JSON.generate(task.wait_result)
+ensure
+  Phronomy.reset_runtime!
+end
+```
+
+The output is `{"text":"saved"}`. Return a value from the transaction. A bound
+view or resource handle becomes invalid after the block finishes, even if it
+was returned through TaskResult. Scope also rejects access from another thread.
+Exceptions and invalid non-local block exits roll back through the existing
+backend rules; no new transaction implementation is introduced.
+
+## Admission, cancellation and ownership
+
+Construction starts no Runtime. Each call resolves the current default pool,
+unless an explicit caller-owned `pool:` was supplied. Runtime reset does not
+transfer ownership of an injected pool.
+
+Admission uses `on_full: :raise`: a full or stopped pool raises immediately.
+Queue wait counts toward `timeout`. Cancellation/timeout before worker pickup
+skips the transaction. After work starts, TaskResult may settle while the
+physical transaction continues and commits. A timeout or cancellation is **not
+a rollback guarantee**. The client does not kill a thread, add retries, or claim
+that an uncertain commit succeeded or failed. Applications needing a durable
+outcome must reconcile through their domain's identities and stored state.
+
+## Existing Agent, Workflow and coordination operations
+
+Internal `Storage::AsyncClient.submit(pool:)` accepts an existing synchronous
+storage unit. This is private framework API, not an application extension API.
+It submits exactly once and adds no transaction, token, or timeout. This lets
+domain operations preserve their own transaction and reconciliation boundaries.
+See the [operation inventory](../architecture/storage-execution-boundaries.md).
+
+In particular, a Workflow runner may have only an injected repository rather
+than access to its raw backend. Internal submit therefore accepts a callable
+and the owner's pool; it does not require a dummy backend or a Persistence
+facade. Public transaction_async requires a real SPI 2 backend.
+
+Durable commit/readback policy, admission release, callback delivery and the
+application of results to live state remain with Agent/Workflow/MultiAgent.
+No cancellation condition is added to existing terminal saves. Tool execution,
+authorization, tracing and application approval listeners retain their own
+execution boundaries.
+
+## ContentStore path and diagram
+
+P4 originally moved `ContentStore::StoredContents` into
+`content_store/backends/stored_contents.rb`. [ADR-062](../decisions/062-content-store-service.md)
+supersedes that split: the implementation now lives at
+`content_store/stored_contents.rb`, beside its shared API and owned schema.
+The obsolete backend directory and collapse entry are deleted without a shim.
+Its constant, synchronous operations, digest rules and exceptions are unchanged.
+Use normal `require "phronomy"`; internal file paths are not a public load API.
+Zeitwerk still collapses `storage/async/`. `Storage::Backends` remains a namespace.
+ContentStore receives no artificial async API.
+
+M10 is G57 Content Service in B3, outside Backend Contracts/Implementations;
+M73 is retired. M69 Storage AsyncClient stays in B4. Text panels are transparent.
+Arrows targeting M33/M41/M44 are hidden by display settings; all measured
+dependencies, source evidence and matrix cells remain available.

data/docs/migrations/vector-async-clients.md

@@ -0,0 +1,110 @@
+# VectorStore and Embeddings: asynchronous client migration
+
+This unreleased P3 change moves the Beta asynchronous API to explicit clients.
+It changes the receiver used by callers. Backend authors continue to implement
+only synchronous methods; method arguments and results remain unchanged.
+
+| Previous receiver | New receiver |
+|---|---|
+| `store.add_async(...)` | `async_store.add_async(...)` |
+| `store.search_async(...)` | `async_store.search_async(...)` |
+| `store.remove_async(...)` | `async_store.remove_async(...)` |
+| `store.clear_async(...)` | `async_store.clear_async(...)` |
+| `embeddings.embed_async(text, token, timeout: seconds)` | `async_embeddings.embed_async(text, token, timeout: seconds)` |
+
+Construct the clients with `VectorStore::AsyncClient.new(backend: store)` and
+`VectorStore::Embeddings::AsyncClient.new(adapter: embeddings)`. The embedding
+cancellation token stays positional. Synchronous `add`, `search`, `remove`,
+`clear`, `size` and `embed` stay on the existing backend objects.
+
+`VectorStore::AsyncBackend` and inherited async methods are removed. There is
+no include/prepend, backend `.async` factory, or automatic compatibility shim.
+Update the receiver wherever an application previously called an async method.
+The clients are public Beta API; their `async/` directories do not introduce
+`Phronomy::Async` or feature-specific `Async` namespaces.
+
+## Complete offline example
+
+This example uses an intentionally simple local embedding adapter to demonstrate
+the API. It needs no provider key, network request, or database server. The
+implementation supplies only `embed`; Phronomy supplies asynchronous execution.
+Run it against a checkout containing P3, not the previously released 0.27.0 gem.
+
+```ruby runnable
+require "phronomy"
+require "json"
+
+class KeywordEmbeddings < Phronomy::Embeddings::Base
+  protected
+
+  def perform_embed(text, cancellation_token = nil)
+    cancellation_token&.raise_if_cancelled!
+    words = text.downcase
+    [words.include?("ruby") ? 1.0 : 0.0,
+      words.include?("python") ? 1.0 : 0.0]
+  end
+end
+
+begin
+  store = Phronomy::VectorStore::InMemory.new(dimension: 2)
+  embeddings = KeywordEmbeddings.new
+  async_store = Phronomy::VectorStore::AsyncClient.new(backend: store)
+  async_embeddings = Phronomy::Embeddings::AsyncClient.new(adapter: embeddings)
+
+  {"ruby" => "Ruby guide", "python" => "Python guide"}.each do |id, title|
+    async_embeddings.embed_async(title).flat_map do |vector|
+      async_store.add_async(id: id, embedding: vector, metadata: {title: title})
+    end.wait_result
+  end
+
+  matches = async_embeddings.embed_async("Ruby").flat_map do |vector|
+    async_store.search_async(query_embedding: vector, k: 1)
+  end.wait_result
+  puts JSON.generate(matches)
+ensure
+  Phronomy.reset_runtime!
+end
+```
+
+The result contains the `ruby` document. The application waits only outside
+worker callbacks; `flat_map` returns the next TaskResult without blocking a
+worker on another operation. `Tools::VectorSearch` continues to call synchronous
+`embed` and `search` inside its existing execution boundary, so this migration
+does not add nested offload work to that Tool.
+
+## Execution and cancellation
+
+Both clients accept optional `pool:` injection. Usually omit it. Construction
+starts no Runtime, and each operation resolves the current default pool. An
+explicit pool remains caller-owned across Runtime resets; it must provide the
+existing OffloadPool submit contract, including its timer service for timeouts.
+
+Queue admission uses `on_full: :raise`. A full or stopped pool raises immediately;
+an accepted operation returns the original TaskResult. Timeout includes queue
+wait. Cancellation or timeout before worker pickup skips the operation; after
+execution starts it settles the result without forcibly stopping I/O or undoing
+backend effects. These are the existing OffloadPool semantics.
+
+Synchronous RBS signatures accept the structural `_CancellationSignal`
+interface, which requires only `raise_if_cancelled!`. Existing
+`Concurrency::CancellationToken` objects still satisfy it. Async RBS signatures
+live in `sig/phronomy/vector_store/async/async_client.rbs` and
+`sig/phronomy/embeddings/async/async_client.rbs` and retain the full CancellationToken
+and TaskResult contract needed by the execution pool. Do not substitute a
+minimal synchronous signal for an async operation's full token.
+
+## Source ownership
+
+The public class names below are unchanged. Their implementation files move:
+
+| Public class | New path under `lib/phronomy/` |
+|---|---|
+| `VectorStore::InMemory` | `vector_store/backends/in_memory.rb` |
+| `VectorStore::Pgvector` | `vector_store/backends/pgvector.rb` |
+| `VectorStore::RedisSearch` | `vector_store/backends/redis_search.rb` |
+| `VectorStore::Embeddings::RubyLLMEmbeddings` | `embeddings/backends/ruby_llm_embeddings.rb` |
+
+Use `require "phronomy"` and the public constants. Direct partial-load paths are
+not the public loading contract; no require shim is kept in the contract
+directories. Backend Contracts have no execution or implementation dependency.
+P4 Storage/ContentStore work remains pending.

data/docs/ordered-event-delivery.md

@@ -0,0 +1,54 @@
+# Ordered event delivery
+
+Load the application integration explicitly:
+
+```ruby
+require "phronomy"
+require "phronomy/integrations/ordered_event_delivery"
+
+Phronomy::Integrations::OrderedEventDelivery.open(
+  capacity: 256, batch_size: 32, flush_timeout: 30,
+  deliver: ->(payload) { send_to_application_transport(payload) }
+) do |delivery|
+  agent = MyAgent.new(on_event: ->(event) {
+    payload = application_payload(event)
+    delivery.publish(payload) if payload
+  })
+  agent.stream("Hello")
+end
+```
+
+The block runs on the external caller, and its result is returned after drain.
+`open` rejects EventLoop callers before executing their block. Publication only
+snapshots and queues plain data; it does not wait for capacity or send network
+traffic. The existing Blocking API supplies a worker only while draining. The
+integration creates no scheduler and never shuts down the shared Runtime/pool.
+
+The app owns authentication, destination, authorization, Rails executor wrapping,
+event-to-payload conversion, and any token coalescing. `prepare_batch:` optionally
+receives an immutable Array of snapshots on the drain worker and returns an Array
+of payloads to send in order. Its default is no transformation. Example 18 passes
+its own TokenEventBatch, preserving adjacent-token coalescing with equal metadata.
+
+Capacity limits the waiting queue, excluding an already extracted batch. Multiple
+publishers are ordered by queue admission, not by thread start time. Hashes,
+Arrays, Strings and scalar plain values are copied into immutable snapshots;
+cycles, non-finite numbers and arbitrary objects fail publication.
+
+On overflow/invalid publication, acceptance closes and the failure remains visible
+to final drain even if an Agent listener merely logs its exception. Previously
+accepted work drains if transport is healthy. A failed batch conversion, delivery
+or worker admission also closes acceptance; remaining work may not be delivered.
+There is no silent drop-as-success, automatic retry or durable delivery guarantee.
+
+`close_and_wait` can be called by multiple external threads. It waits for physical
+drain completion, not just TaskResult settlement. A timeout ends only the wait;
+a network operation can still complete afterwards. Configure transport timeouts
+in the transport itself. Network failure does not prove that nothing was sent.
+
+If application execution fails, its original exception, message and backtrace
+remain primary after cleanup. A simultaneous delivery failure is reported through
+the configured Phronomy logger. Without a logger there is no durable diagnostic
+guarantee; logger failure falls back to stderr without replacing the primary error.
+If only delivery fails, that failure is raised. The small final-answer-only Job
+needs no queue and is unchanged.

data/docs/persistence-backends.md

@@ -2,8 +2,11 @@
 
 [ADR-058](decisions/058-neutral-storage-primitives.md) defines the current
 extension contract. This is an intentional breaking replacement of the old
-fixed-repository Backend SPI. Application code keeps `Persistence.new(backend:)`,
-`Persistence.in_memory`, its eight domain repositories and result queries.
+fixed-repository Backend SPI. Application construction now uses
+`PersistenceComposition.build(backend:)` or `.in_memory`; pass its `agent`, `team`,
+or `workflow` component to that domain. `Persistence.new(backend:)` provides only
+the neutral coordinator. The old eight-repository facade and its queries were
+removed; see [r8 unit 3](architecture/r8-unit3.md).
 
 ## Ownership and composition
 
@@ -13,9 +16,10 @@ record types, active-execution policy, content digest algorithm or watermark API
 
 Agent, Team, Workflow and ContentStore declare their own resource schemas.
 `PersistenceComposition::StorageSchema` gathers those declarations and
-`PersistenceComposition::Repositories` assembles domain wrappers over a View.
-The Team and Workflow schema files live beside their features in nested loader
-roots; loading metadata does not load their runtime implementations.
+`PersistenceComposition` binds domain record adapters to one coordinator.
+Team and Workflow schemas live in their existing `persistence/` implementation
+directories. An isolated Agent uses `PersistenceComposition.agent` and does not
+construct Team or Workflow stores.
 `ContentStore::StoredContents` owns SHA-256 identity and digest verification.
 The Agent-owned `Watermark` composes guarded revision and stream-head conditions.
 
@@ -41,11 +45,10 @@ view.check!(guards: guards, conditions: conditions)
 
 The backend declares `spi_version: 2` and true values for `atomic_resources`,
 `record_cas`, `stream_cas`, `conditional_unique`, `guarded_checks` and
-`nested_savepoints`. Persistence validates these capabilities and the required
-resource declarations before exposing repositories. Old duck-typed backends are
-rejected with `UnsupportedBackendError`; there is no eight-slot compatibility
-adapter. Public Persistence capabilities retain `atomic_all`, `atomic_admission`
-and `optimistic_revision`, derived by composition from these primitives.
+`nested_savepoints`. Persistence validates backend capabilities; composition
+validates the required domain resource declarations before binding adapters.
+Unsupported backends raise `Persistence::UnsupportedBackendError`. There is no
+eight-slot compatibility adapter or duplicated facade capability API.
 
 A root handle routes to the current transaction on the same backend/thread.
 A bound view and all its handles expire on commit or rollback and reject use from
@@ -139,12 +142,24 @@ stale revisions and ordinary constraint conflicts remain `ConflictError`.
 meanings; `TransactionError` identifies invalid scope use. The removed
 `ActiveExecutionConflictError` and `Storage::Repositories` have no aliases.
 
-The following sections describe the retained **domain Persistence** surface.
+The following sections describe the **domain-owned record protocols**, used by
+domain implementations and backend conformance tests. They are not a shared
+application facade. Unqualified
+ConflictError, NotFoundError, SerializationError and UnsupportedBackendError in
+these domain sections refer to `Phronomy::Persistence` errors. Repository exits
+translate the four raw Storage categories, preserving `cause`, message and trace.
+Backend implementation code continues to raise `Phronomy::Storage` errors as
+specified above. Unknown/transport errors and Storage::TransactionError are not
+translated. See [ADR-061](decisions/061-persistence-failure-contracts.md) and the
+[application migration](migrations/persistence-failure-contracts.md).
 
 ## Contents repository
 
-`ContentStore::StoredContents < ContentStore::Base` supplies this domain surface
-over neutral Blobs, with text/JSON helpers and canonical content-ID calculation.
+`ContentStore::StoredContents < ContentStore::Base` supplies text/JSON helpers
+and canonical content-ID calculation over neutral Blobs. The private
+Persistence::ContentRepository adapts its primitive methods to the upper failure
+contract when accessed through `persistence.contents`. Direct StoredContents
+callers retain the raw Storage error surface.
 
 Required primitive surface:
 
@@ -159,7 +174,7 @@ Required semantics:
 - content is immutable and content-addressed;
 - writing identical bytes is idempotent and returns the same content ID;
 - `fetch` returns a binary `String` isolated from caller mutation;
-- a missing content ID raises `Storage::NotFoundError`;
+- a missing content ID through `persistence.contents` raises `Persistence::NotFoundError`;
 - one content ID must never resolve to different bytes; a digest-integrity
   violation raises `ContentStore::IntegrityError`.
 
@@ -361,8 +376,9 @@ Array of supported values
 Hash with String/Symbol keys and supported values
 ```
 
-If a value cannot be represented, raise `Storage::SerializationError` rather
-than silently converting it into a lossy form. JSON backends may return String
+If a value cannot be represented, the backend/codec raises
+`Storage::SerializationError`; the domain repository exposes
+`Persistence::SerializationError`. Do not silently convert it into a lossy form. JSON backends may return String
 keys after decoding; `WorkflowRunner` deliberately accepts String and Symbol keys
 and normalizes them when comparing durable snapshots.
 
@@ -391,16 +407,17 @@ differs, raise `ConflictError`. On success return `true`.
 The operation must not return a replacement AgentRoot or Journal. A mismatch is a
 conflict, not a request to reload/merge mutable state.
 
-When used inside `Persistence#transaction`, a SQL backend should perform the
+When used inside `Agent::Store#transaction`, a SQL backend should perform the
 watermark check in the same database transaction as the subsequent durable
 write.
 
 ## Transaction contract
 
-A transaction block may combine operations across all repositories:
+A domain transaction combines its own record operations. Multiple domains join
+one coordinator scope explicitly; each receives only its own record protocol:
 
 ```ruby
-persistence.transaction do |tx|
+stores.agent.transaction do |tx|
   tx.assert_agent_watermark!(...)
   content_ref = tx.contents.put_text("...")
   tx.journals.append(...)
@@ -493,7 +510,7 @@ require "phronomy"
 require "phronomy/testing/persistence_contract"
 
 RSpec.describe MyPersistenceBackend do
-  let(:persistence) { Phronomy::Persistence.new(backend: described_class.new(...)) }
+  let(:stores) { Phronomy::PersistenceComposition.build(backend: described_class.new(...)) }
 
   it_behaves_like "a persistence content store"
   it_behaves_like "an Agent repository"
@@ -507,7 +524,7 @@ RSpec.describe MyPersistenceBackend do
 end
 ```
 
-`Persistence.in_memory` is run through the same shipped contract source in
+`PersistenceComposition.in_memory` is run through the same shipped contract source in
 Phronomy CI. The files under `spec/support/shared_examples/` are compatibility
 require wrappers only; the authoritative shared-example implementations live
 under `lib/phronomy/testing/persistence_contract/` so the core suite and external

data/docs/runtime-and-concurrency.md

@@ -292,7 +292,7 @@ remain durable conflict defense rather than distributed ownership.
 ## Tool execution modes
 
 The default dispatch helper is the private
-`Phronomy::Agent::Context::Capability::ToolExecutor`, colocated with Capability
+`Phronomy::Tool::ToolExecutor`, colocated with Capability
 Base. Agent ToolInvocation supplies Runtime and admission policy for the
 standard path, and owns authorization and logical result handling. Custom
 `call_async` implementations keep the public Tool protocol. This ownership is
@@ -577,10 +577,35 @@ TaskResult reports only caller-facing settlement.
 ## EventLoop metrics
 
 `Phronomy::Metrics.snapshot` also reports EventLoop queue depth and lag values.
+
+Metrics and Diagnostics only observe resources already owned by the default
+Runtime. Calling `Metrics.snapshot`, `Diagnostics.snapshot` or `Diagnostics.dump`
+does not initialize a Runtime, pool, EventLoop or timer. Missing resources report
+zero values, including `offload_pool_size: 0` when no default pool exists. Once a
+pool exists, this field remains its configured capacity, not a live-worker count.
+Named pools are not aggregated into the default-pool metrics.
+
+Retained resources remain observable during and after shutdown, including
+incomplete cleanup. Observation does not reopen admission or change a shutdown
+result. After the default Runtime is reset, missing resources again report zero;
+the next snapshot uses any newly initialized default Runtime. Counters are sampled
+independently and do not constitute an atomic cross-resource snapshot.
 Use these to distinguish worker saturation from EventLoop backlog/latency.
 
 ## Shutdown
 
+Pool creation and registration close atomically before the shutdown resource set
+is captured. Accepted continuations can still acquire resources during Runtime's
+draining phase. Once resource shutdown begins, all pools close admission before
+any pool waits for its workers.
+
+The stop-phase monotonic deadline is shared by EventLoop and every pool join.
+A join timeout does not stop a synchronous worker. Runtime reports incomplete
+cleanup while any worker remains, even if that worker's TaskResult has already
+been cancelled or timed out. It does not forcefully interrupt worker threads.
+See [R8 unit19](architecture/r8-unit19.md) and its
+[migration notes](migrations/r8-unit19.md) for the shutdown budget and result rules.
+
 `Runtime#shutdown` is terminal for that Runtime. It drains/terminates the
 Runtime-owned EventLoop, then closes pools and timers according to the Runtime
 shutdown contract.

data/docs/workflow-completion.md

@@ -0,0 +1,92 @@
+# A bounded Workflow completion recipe
+
+This is a **legacy manual-signal recipe**, retained for compatibility and its
+bounded-lifetime tests. New code should use
+[`task_state`](architecture/dx05-workflow-task-state.md), which owns completion
+correlation and failure propagation for operations started by a Workflow state.
+The helper below is application code and is not a Phronomy integration API.
+Its limitations do not describe the new task-state API.
+
+Use the application-local function below only for **one live waiting stage, with
+no restart, reentry or replacement while its operation is pending**. It separates
+result mapping (application logic) from the repetitive notification plumbing.
+For repeated/resumed stages, the app must put an operation ID in every success
+AND error payload and check it with a receiver-side transition `guard:` before
+applying the payload. Signal admission alone is not that check. The example
+below intentionally does not claim that wider guarantee.
+
+```ruby runnable
+def forward_completion(task, workflow:, workflow_instance_id:, event:, on_delivery_error:)
+  task.on_complete do |payload, operation_error|
+    delivery_error = nil
+    begin
+      accepted = workflow.signal(
+        workflow_instance_id: workflow_instance_id, event: event,
+        payload: operation_error ? {error: operation_error} : payload
+      )
+      delivery_error = Phronomy::Error.new("Workflow did not accept #{event}") unless accepted
+    rescue => error
+      delivery_error = error
+    end
+    on_delivery_error.call(delivery_error) if delivery_error
+  end
+  nil
+end
+
+class RecipeAnswerAgent < Phronomy::Agent::Base
+  agent_definition id: "bounded-completion-recipe", version: 1
+  model "gpt-4o-mini"
+  instructions "Answer briefly."
+end
+class CompletionState
+  include Phronomy::WorkflowContext
+  field :question, type: :replace
+  field :answer, type: :replace
+  field :error_message, type: :replace
+end
+
+agent = RecipeAnswerAgent.new
+errors = Queue.new
+workflow = nil
+workflow = Phronomy::Workflow.define(CompletionState) do
+  initial :asking
+  state :asking
+  state :done
+  entry :asking, ->(state) {
+    task = agent.invoke_async(state.question).map { |result| {answer: result.fetch(:output)} }
+    forward_completion(task, workflow: workflow,
+      workflow_instance_id: state.workflow_instance_id, event: :answer_ready,
+      on_delivery_error: ->(error) { errors << error })
+    state
+  }
+  transition from: :asking, on: :answer_ready, to: :done,
+    action: ->(state, event) {
+      error = event.payload[:error]
+      error ? state.merge(error_message: error.message) : state.merge(answer: event.payload.fetch(:answer))
+    }
+  transition from: :done, to: :__finish__
+end
+final = workflow.invoke({question: "Explain completion handles"},
+  config: {workflow_instance_id: "bounded-recipe"})
+puts final.error_message || final.answer
+raise errors.pop unless errors.empty?
+```
+
+`forward_completion` returns nil after registering one callback. Already-completed
+results are notified immediately. Two registrations are two subscriptions; the
+application avoids duplicates. No task state is changed, no retry is attempted,
+and no callback waits for execution, storage or network delivery.
+
+Operation failures and cancellation notify the Workflow with `{error: error}`.
+A false signal result and a raised signal exception each notify the required
+`on_delivery_error` callback once. A failure of that callback follows TaskResult's
+existing logger policy; it is not retried and does not rewrite the task result.
+The application observes delivery errors and chooses cancellation/recovery.
+
+Signal acceptance does not guarantee transition completion or a durable save.
+Incomplete tasks retain their subscriptions until settlement under the existing
+TaskResult lifecycle. The caller still owns operation cancellation and lifetime;
+this recipe installs no Runtime shutdown hook or global subscription registry.
+
+See [the full application recipe](application-recipes.md#workflow-completion-and-failures)
+for the same failure behavior without extracting this application-local function.

data/gemfiles/http_minimum.gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+eval_gemfile "mcp_1_0.gemfile"
+gem "faraday", "= 2.1.0"
+gem "webmock", require: false