phronomy 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 636ce578204172927316a89f0f65a2bdfda49140822da98cd1eec9230d821105
-  data.tar.gz: 8d776e0ab9bf2775af4e23f77b0b29968a3d4962f8fbd877d3fe9574a3efb306
+  metadata.gz: dd6beeb52633381ff9e249ec18a1dc422234c78e44f479e3549cd3c54591ab04
+  data.tar.gz: 6528144759933b359d2303b1499b678cbd4eb0c747ca9966f0c6542effb28196
 SHA512:
-  metadata.gz: 81a2b295d5fb03d4cd03c6f3ceabca7b62f4e635fc5dd6ed3db31b1c5f59c6031fc38958895a1fc7b8e9fc75394a81181d51529ebb86f310e85cd2300a9395af
-  data.tar.gz: f701f8fd0be60d655e9676c8cbdfec93606cca20769da90b7c67617c9d876cbde51bf18a42531b7cf70079aa12863af022acd21500fe40cff64c04d5a70df6ab
+  metadata.gz: 307b601d09f6113282eef52f3e547d259e728adf0ba9ac481e3d84dc99583b8510ad779c71e0abee8c78f180b3786d6eacb3fea66723432d93f523e7f4be756a
+  data.tar.gz: 6aed95a5486eaaa792e25ad4d058ebc804278dfa2bf648f216d120256154f7f1cccba86c056ec5176f98556f16e7b835c7102dd0129da5474f9ce93f221cbae8

data/CHANGELOG.md

@@ -14,6 +14,37 @@ Release history for 0.14.0 and earlier is archived in
 
 ---
 
+## [0.26.0] - 2026-09-14
+
+### Changed
+
+- Rename the public completion type to `Phronomy::TaskResult`; remove `Task`
+  without a compatibility alias in this development release.
+- Remove `Orchestrator#fan_out` and `#fan_out_async`. Use `dispatch_parallel`
+  for Agent-specific construction/knowledge/concurrency policy, or Execution
+  for application-defined JOB composition.
+- Preserve cancelled states and original cancellation errors across result
+  transformations, independently of failures that carry CancellationError.
+
+### Added
+
+- `TaskResult#flat_map`, `.all_settled`, and immutable input-order Outcome records.
+- `Execution.run_async` / `.run` for shared runtime fan-out/fan-in, explicit
+  invocation context, whole-execution timeout/cancellation and partial snapshots.
+- `Execution#observe` for scoped continuations of externally owned results.
+- Optional `invocation_context:` on `Blocking.call_async`, with one-way combined
+  context and individual controls shared with Agent admission.
+
+### Fixed
+
+- Dispose finished execution subscriptions and timers while retaining required
+  physical completion tracking. Orchestrator reuses the common Execution engine.
+
+See [Result composition and Execution](docs/async-composition.md) for migration,
+completion boundaries, cancellation and application responsibilities.
+
+---
+
 ## [0.25.0] - 2026-09-12
 
 ### Added

data/CONTRIBUTING.md

@@ -98,16 +98,16 @@ Do not change Ruby visibility merely to make it match an `@api` annotation.
 
 ### Async completion boundary
 
-`Phronomy::Task` is the caller-facing completion handle. EventLoop/FSMSession and
+`Phronomy::TaskResult` is the caller-facing completion handle. EventLoop/FSMSession and
 OffloadPool are execution/continuation mechanisms, not competing completion
 abstractions.
 
 Synchronous work that requires execution away from EventLoop must use an
 OffloadPool. Do not create production worker Threads in adapters, backends, or
 Tools to emulate asynchronous behavior. Logical waits between Phronomy
-lifecycles stay on EventLoop/FSMSession and settle a Task later.
+lifecycles stay on EventLoop/FSMSession and settle a TaskResult later.
 
-The framework owns Task settlement (`complete`, `fail`, and framework-driven
+The framework owns TaskResult settlement (`complete`, `fail`, and framework-driven
 cancellation). Application code should observe Tasks through `wait_result`,
 `on_complete`, `map`, and settlement state. Operation-wide cancellation of
 OffloadPool work is supplied through `CancellationToken`.
@@ -149,7 +149,7 @@ ambiguous. Do not renumber historical ADRs to repair that legacy collision.
 
 For Agent Context work, ADR-012 and ADR-013 define the current Journal,
 Manifest, Context Policy and persistent Knowledge model. ADR-010 defines the
-EventLoop/FSMSession, Task, and OffloadPool execution boundary. ADR-015 defines
+EventLoop/FSMSession, TaskResult, and OffloadPool execution boundary. ADR-015 defines
 the Tool public façade, extension-SPI boundary, and RBS ownership rules.
 
 Current explanatory architecture starts at [`docs/architecture.md`](docs/architecture.md).

data/README.md

@@ -22,8 +22,10 @@ tracking `main` directly.
 - **Multi-Agent Handoff** — semantic Source-to-Target responsibility transfer with policy-bounded Context projection and persisted active responsibility and exact Target recovery within one Persistence domain.
 - **EventLoop + FSMSession** — the framework control plane for logical lifecycle coordination.
 - **OffloadPool** — bounded operating-system-thread execution boundary for synchronous work that must not run on EventLoop.
-- **Task** — the common thread-free completion handle returned by Phronomy asynchronous APIs, including OffloadPool-backed work.
-- **Task.completed / Task.failed** — already-settled application results without starting execution.
+- **TaskResult** — the common thread-free completion handle returned by Phronomy asynchronous APIs, including OffloadPool-backed work.
+- **TaskResult.completed / TaskResult.failed** — already-settled application results without starting execution.
+- **TaskResult.map / flat_map / all_settled** — result transformation, asynchronous chaining and ordered all-settled observation.
+- **Execution.run_async / run** — start application JOBs and join their final results under a whole-execution timeout and cancellation scope.
 - **Blocking.call_async** — submits synchronous application work to the existing bounded OffloadPool without waiting for queue space.
 - **Journal / Context Policy / Manifest** — canonical history plus per-LLM-call context selection.
 
@@ -86,8 +88,8 @@ class. The legacy `Phronomy::Agent::Context::Capability::Base` constant remains
 valid for compatibility.
 
 For non-blocking top-level use, call `invoke_async` and keep the returned
-`Phronomy::Task`. Inside Phronomy lifecycle callbacks, do not block waiting for
-another Task; continue through explicit events instead.
+`Phronomy::TaskResult`. Inside Phronomy lifecycle callbacks, do not block waiting for
+another TaskResult; continue through explicit events instead.
 
 ```ruby
 task = ResearchAgent.new.invoke_async("Research Ruby AI frameworks")
@@ -128,14 +130,14 @@ Runtime
 └─ EventLoop-driven timers
 
 EventLoop / FSMSession ─┐
-                       ├─> Task = completion handle
+                       ├─> TaskResult = completion handle
 OffloadPool ────────────┘
 ```
 
 Logical waiting remains in EventLoop/FSMSession state. Synchronous work that
 would block EventLoop uses the bounded OffloadPool. OffloadPool-specific queue,
 worker, timeout, and abandonment state remains private runtime machinery; callers
-observe completion through `Phronomy::Task`. See
+observe completion through `Phronomy::TaskResult`. See
 [Runtime and concurrency](docs/runtime-and-concurrency.md) for the detailed
 contracts, timeout/cancellation semantics, metrics, and callback rules.
 
@@ -144,7 +146,8 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 - [Getting started](docs/getting-started.md) — installation, RubyLLM setup, Agent/Workflow basics, persistence, streaming.
 - [Features and API stability](docs/features.md) — public feature matrix and stability labels.
 - [Architecture](docs/architecture.md) — canonical current explanatory architecture entry and authority navigation.
-- [Runtime and concurrency](docs/runtime-and-concurrency.md) — EventLoop, FSMSession, Task, OffloadPool, cancellation, observability.
+- [Runtime and concurrency](docs/runtime-and-concurrency.md) — EventLoop, FSMSession, TaskResult, OffloadPool, cancellation, observability.
+- [Result composition and Execution](docs/async-composition.md) — application JOBs, map/flat_map, fan-in snapshots, context ownership and migration.
 - [MCP client](docs/mcp-client.md) — Model Context Protocol (MCP) integration and supported schema subset.
 - [Migration from 0.15-era APIs](docs/migrations/0.15.md).
 - [0.16 cleanup migration](docs/migrations/0.16.md).

data/benchmark/bench_regression.rb

@@ -102,7 +102,7 @@ stub_agent_class = Class.new(Phronomy::Agent::Base) do
   end
 
   define_method(:invoke_async) do |input, **_kw|
-    task = Phronomy::Task.deferred(name: "bench-stub")
+    task = Phronomy::TaskResult.deferred(name: "bench-stub")
     begin
       task.complete(invoke(input))
     rescue => error

data/docs/architecture/agent-context.md

@@ -133,7 +133,7 @@ reconcilable
 resolution_required
 ```
 
-Recovery does not restore the old Ruby object graph or old Task callbacks. It
+Recovery does not restore the old Ruby object graph or old TaskResult callbacks. It
 reconstructs current logical state from durable evidence and continues only
 when authority and outcome certainty permit it.
 

data/docs/architecture/persistence.md

@@ -38,7 +38,7 @@ Durable examples include AgentRoot, Journal records, AgentExecution records,
 content/Manifest references, and durable Workflow snapshots.
 
 Runtime-only examples include FSMSession objects/IDs, AgentInvocation objects,
-Task instances/callbacks, EventLoop entries, Runtime admission entries, and
+TaskResult instances/callbacks, EventLoop entries, Runtime admission entries, and
 in-flight Provider/Tool operation objects.
 
 Runtime/process loss removes Runtime-only objects but does not imply confirmed
@@ -85,7 +85,7 @@ The canonical logical/durable Workflow identity is `workflow_instance_id`, which
 is separate from one Runtime `fsm_session_id`.
 
 Workflow same-process admission is acquired before durable hydration and retained
-through the authoritative terminal/halted save barrier. The caller-facing Task
+through the authoritative terminal/halted save barrier. The caller-facing TaskResult
 settles after that authoritative durable barrier.
 
 See

data/docs/architecture/tracing.md

@@ -75,7 +75,7 @@ The same principle applies to Workflow run/resume operations.
 One active Agent run/resume segment.
 
 The span starts after `execution_id` has been established and the active segment
-is about to run. It ends when that segment's caller-facing Task settles.
+is about to run. It ends when that segment's caller-facing TaskResult settles.
 
 Suspension closes the active span. Later approval/recovery continuation creates a
 new `agent.execution` span correlated by the same logical `execution_id`.
@@ -85,7 +85,7 @@ execution.
 
 ### `workflow.execution`
 
-One Workflow run/resume operation, ending with that operation's Task settlement.
+One Workflow run/resume operation, ending with that operation's TaskResult settlement.
 The durable identity is `workflow_instance_id`.
 
 ### `llm.call`
@@ -131,7 +131,7 @@ API, EventLoop span registry, or durable span state.
 A backend such as OpenTelemetry may preserve natural lexical nesting where its
 own context is active. That adapter behavior does not establish a Phronomy-wide
 guarantee that automatic spans form one backend-native parent/child tree across
-Task/EventLoop/Offload/Runtime boundaries.
+TaskResult/EventLoop/Offload/Runtime boundaries.
 
 ## 8. `trace_pii`
 

data/docs/async-composition.md

@@ -0,0 +1,205 @@
+# Result composition and Execution
+
+`Phronomy::TaskResult` represents a pending or settled result. It does not start
+a thread. `Phronomy::Execution` starts the input JOBs and waits for the final
+TaskResult returned by each JOB. The application defines those completion
+conditions and what to do with the collected values.
+
+## Invocation, individual results and fan-in
+
+```ruby
+require "phronomy"
+
+def collect_answers_async(agents, question:, invocation_context: nil)
+  Phronomy::Execution.run_async(
+    agents, timeout: 30, invocation_context: invocation_context
+  ) do |agent, execution|
+    agent.invoke_async(question, invocation_context: execution.invocation_context)
+      .map { |response| response.fetch(:output).strip }
+  end
+end
+
+# Each outcome identifies the original input position, including failed JOBs.
+outcomes = collect_answers_async(agents, question: "Explain the tradeoff").wait_result
+outcomes.each do |outcome|
+  puts [outcome.index, outcome.status, outcome.value, outcome.error&.message].inspect
+end
+```
+
+`agents` contains separately generated or loaded Agent instances. Use each
+Agent's materialization listener for lifecycle/progress events. Result handling
+uses the TaskResult returned by the invocation.
+
+The input must be an Array. Its positions are shallowly copied before any JOB
+starts. Start blocks run in input order without waiting for previous returned
+results. They can run on the calling thread. Execution adds no per-JOB thread
+or worker: keep start and transformation blocks short and use
+`Blocking.call_async` for application work that can block. A start block itself
+can delay the return of `run_async` if the application performs synchronous work.
+
+Zero, one and many inputs all produce an Array of Outcome records. Empty input
+still validates parameters and rejects an already-expired deadline or cancelled
+token before completing. `Execution.run` starts the same execution once and
+waits for its Outcome Array. The synchronous entrance is rejected on EventLoop
+even for empty or already-completed inputs.
+
+## map and flat_map
+
+| Operation | Success callback | Derived result |
+| --- | --- | --- |
+| `result.map { ... }` | Returns any value | That value, even when the value itself is a TaskResult |
+| `result.flat_map { ... }` | Returns a TaskResult | Waits for and adopts that inner result's terminal value/state |
+| `result.on_complete { \|value, error\| ... }` | Independent completion notification | Returns the original result; the callback does not transform it |
+
+A callback can run immediately during registration or on the completing thread.
+There is no callback thread guarantee. `map`/`flat_map` block StandardError
+failures become failures of the derived result, preserving the original error.
+A wrong `flat_map` return becomes a TypeError failure. Missing blocks raise
+ArgumentError at registration. A source or inner **cancelled state** propagates
+as cancelled with the original error. A failed CancellationError, or one raised
+by an application transformation, stays failed.
+
+For example, extend each JOB through a second Agent before returning its result:
+
+```ruby
+evaluations = Phronomy::Execution.run_async(pairs, timeout: 30) do |pair, execution|
+  context = execution.invocation_context
+  pair.fetch(:author).invoke_async(question, invocation_context: context)
+    .flat_map do |answer|
+      pair.fetch(:reviewer).invoke_async(answer.fetch(:output), invocation_context: context)
+        .map { |review| review.fetch(:output) }
+    end
+end
+```
+
+If a JOB raises StandardError or returns something other than a TaskResult,
+that JOB becomes failed. Other JOBs continue. Once all final results settle,
+the whole execution succeeds with the Outcome Array even if it contains
+individual failures or cancellations.
+
+## Outcome records and whole-execution deadlines
+
+`TaskResult::Outcome` has read-only `index`, `status`, `value` and `error` fields.
+The returned Array and its records are frozen. Values and original exceptions
+are retained by reference, without deep copying or freezing application objects.
+
+| Whole execution | Whole TaskResult | Available records |
+| --- | --- | --- |
+| All JOBs settled | completed | Successful value is the Outcome Array |
+| `timeout:` won | failed, ExecutionTimeoutError | `error.outcomes` |
+| Explicit or inherited token/deadline cancellation won | cancelled, ExecutionCancellationError | `error.outcomes` |
+
+Record statuses are `:completed`, `:failed`, `:cancelled`, and, in an interrupted
+snapshot, `:unfinished`. Unstarted JOBs also have unfinished records. This is
+not another terminal state of TaskResult. A JOB's record refers to its final
+returned result, so completed transformed values are retained; an unfinished
+inner `flat_map` result makes that JOB unfinished.
+
+The execution serializes record updates and terminal claims. The first terminal
+claim wins. At timeout/cancellation it fixes the records before requesting child
+cancellation; later notifications cannot rewrite those records. It does not
+retroactively decide using physical worker completion timestamps.
+
+`timeout:` covers fan-out start through the final JOB results reaching fan-in.
+`nil` adds no deadline. Zero or negative values fail before starting JOBs. It
+accepts finite real Numeric values usable as elapsed seconds; other types raise
+TypeError, and non-finite/complex values raise ArgumentError. These checks occur
+before JOB starts or cancellation subscriptions. The existing Blocking numeric
+conversion rules are unchanged.
+
+`cancellation_token:` accepts nil or a CancellationToken (including subclasses).
+`invocation_context:` accepts nil or an existing InvocationContext (including
+subclasses). Other types raise TypeError at the Execution entrance.
+
+`TaskResult#wait_result(timeout:)` sets only that caller's wait limit. It does not
+cancel or alter the underlying result. Pending waits are forbidden on EventLoop.
+An individual Blocking timeout keeps its TimeoutError failure; an individual
+deadline token keeps the cancellation state. These are distinct from the whole
+execution's errors and snapshot.
+
+## Context, cancellation and ownership
+
+Pass `execution.invocation_context` explicitly to an Agent or to
+`Blocking.call_async(invocation_context: ..., cancellation_token: ...)` for work
+belonging to that execution. The result is bound before it returns to the app;
+its `map`/`flat_map` continuations inherit the scope. A continuation checks the
+scope before running. Explicitly passing the context again when starting an
+inner operation also covers cancellation after the continuation has begun.
+
+An optional existing context contributes its user, policy, budget and tracing
+information by reference. Execution derives a new context without modifying
+the supplied one. Existing context cancellation/deadline and the explicit
+Execution token/timeout all remain effective. Controls connect one way into a
+private token. Cancelling one execution or an individual operation does not
+cancel a parent's or another caller's shared token. Agent and Blocking admission
+combine the individual token with the context's controls.
+
+Scope cancellation stops unstarted scoped operations/transformations and requests
+cooperative cancellation of running operations. It does not use Thread#raise,
+roll back effects, or guarantee physical worker termination. Offload work and
+owned composition steps retain their physical-completion tracking after logical
+cancellation. `on_complete` notifications still run, and suppressed framework
+continuations settle as cancelled rather than remaining pending.
+
+Execution waits only for registered JOBs' returned final results. If a JOB
+starts X and Y but returns Y, the app is responsible for X. Normal completion
+does not discover, join, or sweep-cancel X. If the app explicitly supplied this
+scope to X, its API's cancellation and closed-scope start restrictions still
+apply. A normally closed context cannot be reused to start another operation.
+
+## Observing work started elsewhere
+
+```ruby
+# Source started under its original owner and controls.
+shared_result = existing_agent.invoke_async(question)
+
+run = Phronomy::Execution.run_async([shared_result], timeout: 5) do |source, execution|
+  execution.observe(source).map { |response| response.fetch(:output).upcase }
+end
+```
+
+`observe` returns a distinct scoped result. It does not restart, rebind or cancel
+the source, its existing continuations, or its physical work. A JOB may also
+return an external result directly if it only needs to wait for it.
+
+`TaskResult.all_settled(results)` is the public wait-only API. It accepts an Array
+of TaskResult instances/subclasses, snapshots the positions, and preserves order
+and duplicate positions. Invalid elements cause an immediate TypeError before
+any source is subscribed. It accepts an empty list and has no timeout/cancel
+parameters. It does not own or infer scopes from its sources. If subsequent
+transformations should be scoped, explicitly use
+`execution.observe(TaskResult.all_settled(results)).map { ... }`.
+
+## Whole-result processing and existing layers
+
+The whole TaskResult is the scope exit. An outer `map`/`flat_map` does not inherit
+or extend the completed inner scope, whether registered before or after fan-in.
+For example, vote counting belongs in an outer `map`. A slow save belongs in an
+outer `flat_map` returning `Blocking.call_async(timeout: 5) { ... }`. That new
+operation's five seconds start when it is invoked, independently of the first
+execution's deadline. There is no `compose` argument or separate fan-out entrance.
+
+Execution owns common runtime coordination. Orchestrator remains above the Agent
+layer: `dispatch_parallel[_async]` retains Agent construction, knowledge
+inheritance, bounded active children and `on_error` policy, and delegates its
+runtime coordination to Execution. AgentExecution remains the durable Agent
+record; ExecutionCoordinator keeps admission, persistence, approval, recovery
+and terminal barriers while reusing the common context/control binding.
+
+## Development-release migration
+
+- Replace `Phronomy::Task` with `Phronomy::TaskResult`. The old constant and file
+  are removed; there is no compatibility alias.
+- Replace `orchestrator.fan_out(agent: klass, inputs: inputs, ...)` with
+  `orchestrator.dispatch_parallel(*inputs.map { |input| {agent: klass, input: input} }, ...)`
+  when keeping Orchestrator's Agent construction/knowledge/concurrency policy.
+  Use Execution directly for application-defined JOB result composition.
+- Replace the asynchronous equivalent with `dispatch_parallel_async` or
+  `Execution.run_async` as appropriate. `fan_out` and `fan_out_async` are removed.
+- Keep per-incarnation listeners at Agent creation/load. This change introduces
+  no invocation listener blocks, Proc persistence, durable result transforms,
+  callback acknowledgements or new scheduler.
+
+See examples `32_async_composition` for complete basic and asynchronously
+evaluated majority-vote applications, and `23_bounded_parallel` for bounded
+Agent dispatch. Examples must depend on a core commit containing these APIs.

data/docs/decisions/010-cooperative-first-concurrency.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Accepted — revised for a single Task completion contract and the OffloadPool
+Accepted — revised for a single TaskResult completion contract and the OffloadPool
 execution boundary.
 
 ## Context
@@ -19,7 +19,7 @@ executes is separate from the object used by callers to observe completion.
 ## Decision
 
 Framework lifecycle coordination uses one Runtime-owned EventLoop and explicit
-FSMSession state/events. **`Phronomy::Task` is the single caller-facing completion
+FSMSession state/events. **`Phronomy::TaskResult` is the single caller-facing completion
 handle**, not an execution backend.
 
 There are two framework execution mechanisms:
@@ -28,22 +28,22 @@ There are two framework execution mechanisms:
 - **OffloadPool** for synchronous work that must execute on bounded worker OS
   Threads away from EventLoop.
 
-Both mechanisms surface asynchronous completion as `Phronomy::Task`.
+Both mechanisms surface asynchronous completion as `Phronomy::TaskResult`.
 
 Phronomy defines two Tool execution modes:
 
 - `:cooperative` — short, EventLoop-safe work, or a specialized asynchronous
   implementation that starts another Phronomy lifecycle and immediately returns
-  a Task;
+  a TaskResult;
 - `:offloaded` — synchronous work that must not run on EventLoop. It executes in
-  the bounded OffloadPool and returns a Task.
+  the bounded OffloadPool and returns a TaskResult.
 
 Workload classification such as I/O-bound versus CPU-bound is application-owned.
 Phronomy does not provide separate `:blocking_io`, `:cpu_bound`, or
 `:external_process` Tool execution modes.
 
 Logical waits are never offloaded merely to obtain concurrency. Waiting for an
-Agent, Workflow, ToolInvocation, approval, timer, or another Task is represented
+Agent, Workflow, ToolInvocation, approval, timer, or another TaskResult is represented
 as FSMSession state plus a later EventLoop event.
 
 ## Runtime model
@@ -65,7 +65,7 @@ Runtime
 └─ EventLoop-driven timers
 
 EventLoop / FSMSession ─┐
-                       ├─> Task = completion handle
+                       ├─> TaskResult = completion handle
 OffloadPool ────────────┘
 ```
 
@@ -91,11 +91,11 @@ resource domains.
 An EventLoop action must not block while waiting for a free OffloadPool queue
 slot. Framework-owned EventLoop-origin submissions therefore use non-blocking
 admission (`on_full: :raise`) and propagate `BackpressureError` through the normal
-FSM/Task completion path.
+FSM/TaskResult completion path.
 
 ## Timeout and cancellation
 
-An OffloadPool submit-time timeout settles the caller-facing Task with
+An OffloadPool submit-time timeout settles the caller-facing TaskResult with
 `TimeoutError`. It does not asynchronously interrupt a running worker Thread. If
 execution has already started, the private Operation becomes abandoned, the
 worker may continue until the submitted synchronous call returns, and that
@@ -104,8 +104,8 @@ eventual worker result is discarded.
 The cancellation token passed to `OffloadPool#submit` follows the same model:
 
 - cancellation before worker execution prevents the submitted block from
-  starting and settles the Task as cancelled;
-- cancellation after worker execution starts settles the Task immediately, marks
+  starting and settles the TaskResult as cancelled;
+- cancellation after worker execution starts settles the TaskResult immediately, marks
   the private Operation abandoned, and allows the worker to continue;
 - cancellation does not use `Thread#raise`;
 - application code may observe the same CancellationToken and terminate its own
@@ -114,18 +114,18 @@ The cancellation token passed to `OffloadPool#submit` follows the same model:
 A submit token with a monotonic deadline is connected to the Runtime timer queue,
 so deadline expiry becomes explicit cancellation without a polling Thread.
 
-`Task#wait_result(timeout:)` is a synchronous bridge for non-EventLoop callers.
+`TaskResult#wait_result(timeout:)` is a synchronous bridge for non-EventLoop callers.
 Its timeout is waiter-local: it raises `TimeoutError` only to that caller and does
-not settle the Task, cancel the submitted operation, or mark an OffloadPool
+not settle the TaskResult, cancel the submitted operation, or mark an OffloadPool
 Operation abandoned.
 
-Framework components own Task settlement. Application code should request
+Framework components own TaskResult settlement. Application code should request
 operation-wide cancellation through the CancellationToken accepted by the API
-that created the Task rather than calling Task settlement methods directly. A
-Task cancellation must not implicitly cancel a shared CancellationToken in the
+that created the TaskResult rather than calling TaskResult settlement methods directly. A
+TaskResult cancellation must not implicitly cancel a shared CancellationToken in the
 reverse direction.
 
-Independent `Task#on_complete` notification callbacks are fault-isolated. Their
+Independent `TaskResult#on_complete` notification callbacks are fault-isolated. Their
 execution thread is not guaranteed, so callbacks must be thread-safe and should
 return quickly. Framework lifecycle code normally converts completion into an
 explicit EventLoop event.
@@ -136,7 +136,7 @@ explicit EventLoop event.
 caller-facing timeout or cancellation won after worker execution had already
 started. `offload_pool_abandoned_active` is current-state: it counts only those
 abandoned operations whose synchronous workers are still occupying OffloadPool
-capacity. Task does not expose abandonment as caller-facing completion state;
+capacity. TaskResult does not expose abandonment as caller-facing completion state;
 that distinction remains private OffloadPool execution/observability state.
 
 ## CPU-bound work
@@ -154,7 +154,7 @@ does not reintroduce a Tool-level workload class.
 A component that truly uses a native asynchronous driver and does not create a
 Phronomy-owned OS Thread does not need an OffloadPool worker. If such an
 extension point is formally introduced, it must still adapt completion into a
-`Phronomy::Task`; it must not expose provider-specific futures or private Runtime
+`Phronomy::TaskResult`; it must not expose provider-specific futures or private Runtime
 operation records as Phronomy's completion contract.
 
 The current VectorStore and Embeddings extension contracts are synchronous; their
@@ -168,14 +168,14 @@ OffloadPool worker
   → wait_result
 ```
 
-and equivalently for Workflow/ToolInvocation/Task lifecycles.
+and equivalently for Workflow/ToolInvocation/TaskResult lifecycles.
 
 The correct model is:
 
 ```text
 parent FSMSession
   → start child lifecycle
-  → return Task immediately
+  → return TaskResult immediately
   → child settles
   → post parent EventLoop event
 ```
@@ -183,8 +183,8 @@ parent FSMSession
 ## Consequences
 
 - There is one explicit framework continuation model: FSMSession + EventLoop.
-- There is one caller-facing completion abstraction: Task.
-- Task stays thread-free and represents settlement only.
+- There is one caller-facing completion abstraction: TaskResult.
+- TaskResult stays thread-free and represents settlement only.
 - OffloadPool owns bounded OS-thread execution and its private Operation state.
 - Tool execution classification remains `:cooperative` / `:offloaded`.
 - CPU/I/O classification and resource sizing are application responsibilities.

data/docs/features.md

@@ -46,8 +46,8 @@ rather than implicitly inheriting the parent revision. The Stable
 |---|---|
 | **Knowledge** — Journal-backed persistent Agent context registered with `knowledge:` / `add_knowledge`, selected per LLM call by Context Policy | Beta |
 | **`VectorStore#size`** — Document count for InMemory, RedisSearch, and Pgvector backends | Beta |
-| **VectorStore async convenience** — `add_async` / `search_async` / `remove_async` / `clear_async` offload the synchronous Backend SPI through Phronomy and return `Task`; native async override is not part of the current Backend SPI | Beta |
-| **Embedding async convenience** — `embed_async` offloads synchronous `embed` through Phronomy and returns `Task` | Beta |
+| **VectorStore async convenience** — `add_async` / `search_async` / `remove_async` / `clear_async` offload the synchronous Backend SPI through Phronomy and return `TaskResult`; native async override is not part of the current Backend SPI | Beta |
+| **Embedding async convenience** — `embed_async` offloads synchronous `embed` through Phronomy and returns `TaskResult` | Beta |
 | **Model Context Protocol (MCP) Tool** — `Phronomy::Tools::Mcp` integration through the official `mcp` gem | Beta |
 | **Agent Tool** — `Phronomy::Tools::Agent.from_agent` exposes a child Agent as a Tool without occupying a worker while waiting | Beta |
 | **Vector Search Tool** — `Phronomy::Tools::VectorSearch` wraps VectorStore and Embeddings adapters | Beta |
@@ -64,10 +64,12 @@ rather than implicitly inheriting the parent revision. The Stable
 | **Agent async events** — one Runtime-only `on_event` listener is bound at Agent `new` / `create` / `load`; invoke/stream operations publish through that listener and streaming additionally emits `:token` | Beta |
 | **`stream` / `stream_async`** — Event callbacks execute on EventLoop and must return quickly | Beta |
 | **`stream_callback_error_policy`** — Terminal event callback error policy (`:report` / `:fail_task`) | Beta |
-| **Task completion contract** — `Task` is the common caller-facing completion handle for EventLoop/FSMSession lifecycles and OffloadPool work | Beta |
-| **`Task#map`** — Application-level Task result transformation and error propagation | Stable |
-| **Settled Task factories** — Public `Task.completed` / `Task.failed` represent already available application results without starting execution | Beta |
-| **Blocking.call_async** — Public non-waiting admission of synchronous application work to the existing OffloadPool, returning a Task | Beta |
+| **TaskResult completion contract** — `TaskResult` is the common caller-facing completion handle for EventLoop/FSMSession lifecycles and OffloadPool work | Beta |
+| **`TaskResult#map`** — Application-level TaskResult result transformation and error propagation | Stable |
+| **`TaskResult#flat_map` / `.all_settled`** — Asynchronous chaining and input-order observation of terminal results | Beta |
+| **`Execution.run_async` / `.run`** — Common runtime fan-out/fan-in with whole-execution controls and immutable outcome snapshots | Beta |
+| **Settled TaskResult factories** — Public `TaskResult.completed` / `TaskResult.failed` represent already available application results without starting execution | Beta |
+| **Blocking.call_async** — Public non-waiting admission of synchronous application work to the existing OffloadPool, returning a TaskResult | Beta |
 | **CancellationToken** — Cooperative cancellation with explicit `cancel!`, lazy monotonic deadlines, and callback registration | Experimental |
 | **Tool `execution_mode`** — `:cooperative` for short EventLoop-safe work; `:offloaded` for synchronous work that must stay off EventLoop | Experimental |
 | **OffloadPool sizing** — `offload_pool_size` / `offload_queue_size`; named pools available for application-owned isolation | Beta |
@@ -107,11 +109,11 @@ visibility still follows the intended calling model. `@api private` means
 declaration; some internal methods remain Ruby-public because Phronomy components
 call them through explicit receivers.
 
-`Task` is the caller-facing completion abstraction. Framework components own
+`TaskResult` is the caller-facing completion abstraction. Framework components own
 settlement (`complete` / `fail` / `cancel!`); application code observes Tasks via
 `wait_result`, `on_complete`, `map`, and state readers. Operation-wide cancellation
 is requested through the `CancellationToken` accepted by the API that created the
-Task.
+TaskResult.
 
 Persistence Backend SPI methods, LLMAdapter methods, and other documented
 extension contracts are deliberate exceptions to the ordinary
@@ -147,7 +149,8 @@ private execution machinery, see [Runtime and concurrency](runtime-and-concurren
 
 Static `Orchestrator.subagent` Tools invoked inside a parent AgentExecution reserve
 child Agent/execution identities before dispatch and reuse retained outcomes.
-Direct `dispatch_parallel` / `fan_out` calls remain Runtime-only convenience APIs.
+Direct `dispatch_parallel` calls retain Agent-specific policy and use the common
+runtime Execution engine. The redundant `fan_out` / `fan_out_async` APIs are removed.
 `Orchestrator#resume(execution_id)` continues retained parent coordination.
 
 `TeamCoordinator` requires `team_definition id:, version:` and provides

data/docs/getting-started.md

@@ -180,13 +180,13 @@ Supplying both `on_event:` and a construction block is an error. If `load`
 resolves an already-live same-process Agent, supplying any new listener/block
 is also an error; the existing binding is immutable for that Runtime incarnation.
 
-`Phronomy::Task` is the common caller-facing completion handle for asynchronous
+`Phronomy::TaskResult` is the common caller-facing completion handle for asynchronous
 Phronomy work. Logical lifecycle progress is driven by EventLoop/FSMSession;
 synchronous work that must execute away from EventLoop is submitted to
-OffloadPool. Both paths expose completion as a `Task`.
+OffloadPool. Both paths expose completion as a `TaskResult`.
 
-`Task#wait_result` is for an external caller. Do not block EventLoop waiting for
-a Task that can only complete through that same EventLoop.
+`TaskResult#wait_result` is for an external caller. Do not block EventLoop waiting for
+a TaskResult that can only complete through that same EventLoop.
 
 Streaming uses the same Agent-incarnation listener:
 
@@ -208,7 +208,7 @@ EventLoop and therefore should return quickly.
 ## Human-in-the-loop approval
 
 A Tool requiring approval suspends the durable logical execution without
-settling the original execution Task. Approval notification is delivered
+settling the original execution TaskResult. Approval notification is delivered
 through the same Agent listener as `:approval_required`:
 
 ```ruby
@@ -349,7 +349,7 @@ workflow = Phronomy::Workflow.define(AnswerContext) do
 end
 ```
 
-Returning a `Phronomy::Task` from a Workflow entry/transition action is not an
+Returning a `Phronomy::TaskResult` from a Workflow entry/transition action is not an
 implicit await mechanism and is rejected.
 
 ## Agent as Tool