phronomy 0.27.0 → 0.29.0

data/docs/architecture/agent-chat-and-state-ownership.md

@@ -1,5 +1,11 @@
 # Agent Chat and explicit state ownership (R09, second slice)
 
+> Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
+> adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
+> construction/interception; Tool owns canonical schema validation. See
+> `docs/architecture/r8-unit6.md` and `docs/migrations/r8-unit6.md`.
+
+
 ## Purpose and clients
 
 Agent::Base is the declaration and lifecycle facade used by application Agent
@@ -62,7 +68,7 @@ hook retains application/test overrides of apply_instructions and Orchestrator's
 prepare_tool_class(invocation:) cooperation. Moving it into a builder receiving
 the entire Agent would merely introduce callbacks back into Base.
 
-AgentInvocationSessionBuilder and InvocationRestorer keep using the same hooks.
+InvocationActions and EngineSessionBuilder and InvocationRestorer keep using the same hooks.
 Saved config is authoritative during recovery; current class declarations do
 not overwrite it. A failure stops installation at that operation, propagates
 the same error and does not install later Tools/messages. No new Chat cache,

data/docs/architecture/agent-transition-ownership.md

@@ -1,89 +1,13 @@
-# Agent invocation transition ownership
-
-## Role and scope
-
-An Agent invocation moves between preparation, Provider calls, Tool processing,
-approval suspension and completion. Three collaborators need the same policy:
-AgentInvocation consumes external payloads; PhaseMachineBuilder creates the
-executable state machine; AgentInvocationSessionBuilder configures FSMSession's
-advance, wait and terminal boundaries. Independently maintained event lists and
-transition copies could disagree about what the current phase can accept.
-
-Refactor 39 gives that shared policy one private owner, InvocationTransitions in
-agent/execution. This is Agent data in the existing transition Hash format, not
-a new cross-feature DSL or Engine extension. It is not a new execution object.
-
-## Ownership and reading order
-
-| Owner | Responsibility |
-|---|---|
-| InvocationTransitions | Initial phase, declared/automatic/approval-wait states, Tool event vocabulary and ordered external transition definitions. |
-| PhaseMachineBuilder | Translate those external definitions to state_machines; retain automatic state_completed transitions and synchronous entry-action validation. |
-| AgentInvocationSessionBuilder | Assemble the invocation, event sink, entry actions and machine; pass shared state and transition metadata to FSMSession. |
-| AgentInvocation | Apply payloads and expose the current guard predicates; use the shared Tool event vocabulary. |
-| FSMSession | Generic advancement, event delivery and wait/terminal handling. No Agent-specific decisions. |
-
-Read the policy table for legal external sources and guard priority, the machine
-builder for execution mechanics, and the session builder for action wiring.
-The EXTERNAL_EVENTS Hash, each transition array and each row are frozen so one
-session cannot edit another session's policy. Guard lambdas contain no captured
-invocation state; they inspect the context supplied at transition time.
-Old private constants and the external_events factory are removed without aliases.
-
-## Preserved event and phase contract
-
-The six Tool events are authorized, approval_required, completed, failed,
-rejected and cancelled, each with the tool_ prefix. Each moves waiting_for_tools
-to evaluating_tools. LLM completion from calling_llm tries these in order:
-
-1. callback_failed? to failed;
-2. handoff_failed? to failed;
-3. handoff_requested? to handed_off;
-4. tool_call_pending? to starting_tools;
-5. unconditional fallback to output_filtering.
-
-Guards short-circuit. A nil context skips guarded rows and takes the fallback;
-guard exceptions propagate unchanged. Each evaluation uses the latest context,
-without caching a selected destination. Session applies the event payload first.
-
-LLM failure/setup failure leads from calling_llm to failed. Tool setup failure
-leads from dispatching_tools to failed, while tool_dispatch_prepared returns it
-to evaluating_tools. Resume moves suspended to waiting_for_tools. Application
-callback failure is accepted from the existing nine active phases only.
-
-Automatic phases remain idle, filtering_input, building_context, starting_tools,
-evaluating_tools, recording_tool_results and output_filtering. calling_llm,
-waiting_for_tools and dispatching_tools wait for external events. suspended ends
-a segment with halted; resume uses a fresh Session identity. The four declared
-terminal phases remain handed_off, completed, blocked and failed.
-
-FSMSession reads only the from field when determining external-event admission
-and waiting. It does not execute metadata guards or choose their destinations;
-state_machines does that. Known-but-undeclared and unknown events retain their
-existing error behavior; context-consumed stale events retain their early exit.
-The internal order of event registration now follows the shared table. Transition
-order within each event, which determines behavior, is preserved. The generated
-machine's private event-enumeration order is not a supported public contract.
-
-## Verification and limits
-
-Independent behavioral tests run on both Refactor 38 and the candidate: all 195
-external-event/source-state combinations, all sixteen LLM condition combinations
-including short-circuit order, nil context and guard exceptions, fifteen Session
-boundaries, context-before-guard ordering, approval suspension/resume/dispatch,
-and invalid source-state handling. Existing Agent, causal durability, Handoff,
-Workflow and Engine tests continue to cover their collaborating behavior.
-
-The candidate also runs the full core/integration suites, offline examples and
-real SQLite, API/SPI snapshots, RBS, style, annotations and isolated gem checks.
-No SQL, stored format, entry action implementation, Tool restoration, cancellation
-or Coordinator sequencing is changed. The new contract tests isolate entry actions
-and do not claim live Provider coverage. Live PostgreSQL/LLM and remote CI are
-not executed for this candidate. Refactor 39 was independently verified after application at core 4d57614a,
-tree 654241da4b2b7f32d988602d28127bc1fa155641. All 10 files and the full tree
-matched, and core/integration/examples/SQLite/API/type/gem checks passed.
-The published SVG is applied39-01.
-
-R06 is applied and complete. R07 now has a Refactor 40 candidate; R08/D08, R09
-and R10 remain afterward. R09's inheritance behavior and R10's action names
-are not altered by the transition-ownership work.
+# Agent transition ownership (r8 unit 7)
+
+InvocationTransitions owns both automatic and external transitions, including
+ordered guard evaluation. InvocationActions owns Agent entry operations.
+EngineSessionBuilder configures FSMSession using those definitions;
+PhaseMachineBuilder adapts them to state_machines without defining progress rules.
+ExecutionCoordinator and RecoveryCoordinator retain durable decisions and use
+the Agent-owned ExecutionEnvironment port for execution connection.
+
+See [r8 unit 7](r8-unit7.md) and [ADR-067](../decisions/067-agent-progress-and-engine-connection.md).
+Existing event source validation, callback failure priority, short-circuiting,
+Tool outcome priority, suspended/wait/terminal boundaries and session incarnation
+rules are preserved. Agent's Tool child FSM is still a separate remaining task.

data/docs/architecture/backend-groups.md

@@ -0,0 +1,152 @@
+# Backend responsibilities and asynchronous execution clients
+
+The diagram distinguishes responsibility **groups** from its display layers.
+The earlier B1-B6 horizontal bands and topical columns are restored for
+readability. `G14`, `G46`, `G47` and `G48` remain stable responsibility identifiers;
+boundary permissions follow those responsibilities, not B/G numbers or positions.
+Each source directory keeps its own module box and stable module ID. Restoring
+the display does not undo the separation of backend contracts and execution.
+
+The restored display puts separated Backend Contracts in B5, alongside but
+distinct from Engine Internals and Execution Contracts. B4 holds Async Clients and separately grouped Implementations. Execution
+operations and values now share G58; the former G59 service split is removed. Backend directories awaiting separation remain visibly mixed
+in B4; their contracts move to B5 in their implemented phase. These are display
+positions, not a shared architectural level or namespace.
+
+| Group | Responsibility | Dependency rule |
+|---|---|---|
+| G14 Engine Internals | Runtime, workers, FSM and EventLoop | No feature-specific backend or client dependencies |
+| G58 Execution Framework | Submission protocol, TaskResult, Execution, Blocking, controls and common rules | Only Execution and Common, including neutral settings; Engine implements the mechanism |
+| G46 Async Clients | Execute synchronous backend operations through Execution | Use Backend and Execution contracts; no direct Engine or concrete backend selection |
+| G47 Backend Contracts | Synchronous SPI, values, errors and shared rules | No Engine, Execution Services, Async Client or concrete implementation dependencies |
+| G48 Backend Implementations | Implement the synchronous backend SPI | Depend on the corresponding Contracts; no Engine, Execution Services or client dependencies |
+| G57 Content Service | Content IDs, canonical text/JSON and digest integrity over Storage | Uses neutral Storage and Common; no physical backend, Engine or domain orchestration dependencies |
+
+Composition chooses concrete backends and supplies them to consumers. These
+are source-ownership groups, not shared Ruby namespaces. Synchronous APIs can
+be called directly. Diagram links represent source references; calls through
+injected objects require separate runtime review.
+
+## Implemented phase: P1/P2/P3/P4 (`storage`)
+
+P3 adds public VectorStore and Embeddings AsyncClients. Their synchronous
+contracts and implementations have no Engine dependencies. See the
+[public receiver migration](../migrations/vector-async-clients.md).
+
+### P2: LLM
+
+- Install the AST analyzer, group annotations, SVG formatter and boundary gate
+  in `tools/architecture/`. The Architecture workflow checks the committed
+  phase and generates evidence for its actual checkout SHA.
+- `LLMAdapter::Base` now defines synchronous generation plus chat construction,
+  configuration, message/tool-call values, identity and optional input budget.
+  RubyLLM-specific construction and error translation belong to its backend.
+  Adapter extensions must implement the new operations; no legacy wrapper remains.
+- `LLMAdapter::AsyncClient` owns the internal `complete_async` and `stream_async`
+  operations in `llm_adapter/async/`. It is not a public extension API.
+- `LLMAdapter::RubyLLM` lives in `llm_adapter/backends/` and still inherits Base.
+  Its public name, synchronous signatures and default configuration are unchanged.
+- Zeitwerk collapses these two new directories. Neither `Phronomy::Async` nor
+  `LLMAdapter::Async` / `LLMAdapter::Backends` is introduced.
+- Agent constructs the framework client around the configured synchronous
+  adapter. Custom adapters implement no async methods and need no pool logic.
+
+The client preserves `on_full: :raise`, the original pool TaskResult, token
+forwarding and per-chunk cancellation. Transport timeout/retry stays with the
+adapter/provider. Construction starts no Runtime, and the default pool is
+resolved again on each operation; an injected pool stays caller-owned. Only an
+internal lightweight sink runs on the worker; application event callbacks
+continue to run on EventLoop.
+
+Use `require "phronomy"` and the public constants. The old implementation path
+`phronomy/llm_adapter/ruby_llm` moves to
+`phronomy/llm_adapter/backends/ruby_llm`; arbitrary partial-load paths are not the
+public loading contract. No shim in the contract directory reintroduces an
+implementation dependency. No public RBS or Stable/Beta API snapshot changes
+are needed in this phase; both are verified unchanged.
+
+### P3: VectorStore and Embeddings
+
+- `VectorStore::AsyncClient` owns public add/search/remove/clear async operations;
+  `VectorStore::Embeddings::AsyncClient` owns public `embed_async`.
+- Backends implement only synchronous methods. The old `AsyncBackend` mixin
+  and inherited async methods are removed; application callers change receiver.
+- InMemory, Pgvector, RedisSearch and RubyLLMEmbeddings move into `backends/`
+  directories. Their public constants, synchronous signatures and bodies stay
+  unchanged. Zeitwerk explicitly collapses the new `async/` and `backends/` paths.
+- Synchronous RBS uses structural `_CancellationSignal`; async signatures keep
+  TaskResult and the execution token. The public API snapshot records the new
+  receivers and the intentional removals from Base/InMemory.
+- All three original backend-to-Engine edges are removed. In the measured view,
+  M28/M29 join G47 Contracts in B5. M67/M68 are clients in B4 and M71/M72 are
+  separately grouped implementations. No pending Storage clients are drawn.
+
+### P4: Storage execution
+
+- Public `Storage::AsyncClient#transaction_async` opens the raw backend transaction
+  on a worker and yields its scoped Storage::View. Backends stay synchronous.
+- Private `Storage::AsyncClient.submit(pool:)` executes existing domain units
+  without adding a transaction, timeout or token. All 16 durable submission sites
+  are recorded in the [execution inventory](storage-execution-boundaries.md).
+- M69 is an Async Client and M35 a concrete Storage backend in B4.
+  Existing `Storage::Backends` is not collapsed.
+- See the [public API and transaction rules](../migrations/storage-async-client.md).
+
+### ContentStore service ownership
+
+ContentStore is a content management service using Storage, not a peer physical
+backend. Its API, canonicalization, StoredContents implementation and owned
+StorageSchema live in `content_store/`. Base remains shared by StoredContents
+and the Persistence exception facade. The unnecessary `backends/` subdivision
+and Zeitwerk collapse are removed without a forwarding file or alias.
+
+M10 belongs to G57 Content Service in the persistence column of display band B3.
+M73 is retired, not reused. G47/G48 contain no ContentStore modules. The real
+M10-to-Storage dependency remains in both the drawing and the full graph.
+The boundary gate rejects reverse Storage-to-ContentStore dependencies and any
+service path to a physical backend, Engine, client or domain orchestration.
+Public constants, signatures, content IDs, exceptions and transaction behavior
+remain unchanged. See [ADR-062](../decisions/062-content-store-service.md).
+
+## r8 unit 1 framework boundaries
+
+G58/M76/M77 now owns the common Execution framework under `execution/`.
+Engine owns FSM-specific values and the pool/timer/runtime binding, while
+composition selects that binding. Tracing owns explicit observation. Context
+and Tool now own their shared operations, not merely value/error declarations.
+The former G59/M78 split is retired. See [r8 unit 1](r8-unit1.md) for the exact
+implemented scope, API removals and incomplete Persistence/domain work.
+
+The full architecture still contains existing cycles outside the checked scope.
+The recorded graph is not an ideal final r8 diagram.
+
+## Pending phase
+
+P5 completes the final cross-repository/API/docs review after application.
+All retained P2-P4 responsibilities exist in source; the unnecessary M73 split
+is superseded by G57 service ownership. The measured SVG still comes from
+actual Ruby analysis; the target concept is a separate explanatory artifact.
+
+## Regenerate and review
+
+See [tool instructions](../../tools/architecture/README.md). The normal command
+reads `tools/architecture/phase.json`:
+
+```sh
+python tools/architecture/refresh_diagram.py . tmp/architecture
+```
+
+The output includes the matrix, source hashes, boundary report, module/file
+cycles and the delta from baseline 84668606. Source/module/group changes require
+matching annotation updates. No up/down rule or coordinate controls the gate.
+Ruby loader, RBS, cancellation, admission, streaming and configuration tests
+remain necessary: static analysis does not replace them.
+
+An unpublished local candidate must use `--candidate`. Its SVG states that it
+is unapplied and disables GitHub source links. Applied commits and CI output
+use actual source links. CI artifacts are generated after the source commit;
+there is no self-referential SVG commit hash or automatic commit/push.
+
+Text panels are transparent and module outlines/group colors remain intact.
+Arrows into M33/M41/M44 are hidden by presentation settings; their AST edges,
+source evidence and matrix cells are preserved. Boundary rules inspect all edges.

data/docs/architecture/before-llm-input.md

@@ -28,10 +28,10 @@ candidates are accumulated in hook order.
 
 ## 3. Input and result
 
-Hooks receive immutable `Phronomy::Agent::LLMInputBuildContext` metadata. They do
+Hooks receive immutable `Phronomy::Context::LLMInputBuildContext` metadata. They do
 not receive a mutable Provider chat/message array.
 
-A hook returns `Phronomy::Agent::LLMInputPatch` or `nil`.
+A hook returns `Phronomy::Context::LLMInputPatch` or `nil`.
 
 These two types live in the shared `agent/context_contract/` implementation
 directory together with the Policy input and result contracts. Zeitwerk
@@ -40,7 +40,7 @@ names. Hook registration, invocation, and result handling are unchanged; see
 [ADR-036](../decisions/036-context-contract-ownership.md).
 
 ```ruby
-Phronomy::Agent::LLMInputPatch.new(
+Phronomy::Context::LLMInputPatch.new(
   model_config_patch: {temperature: 0.2},
   segment_candidates: [
     {

data/docs/architecture/context-management.md

@@ -85,7 +85,7 @@ same abstraction level.
 Application code supplies an ordinary reusable Ruby strategy object:
 
 ```ruby
-class SearchContextPolicy < Phronomy::Agent::ContextPolicy
+class SearchContextPolicy < Phronomy::Context::ContextPolicy
   def initialize(search:)
     @search = search
   end

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

@@ -0,0 +1,119 @@
+# Agent scope and incarnation lifetime (DX05-E core)
+
+An application decides how long it needs an Agent. C04 owns the mechanics for
+acquiring that incarnation and releasing it safely. A scope does not delete saved
+Agents, stop other Agents, close an application-owned Store, or infer whether a
+business operation should be retried.
+
+## Application change
+
+Before, a long-running application could create Agents for each request, but
+the Runtime retained their mutable incarnations until shutdown. `close!` changes
+the durable Agent lifecycle; `purge!` deletes saved state. Neither is a substitute
+for releasing a process-local incarnation.
+
+```ruby
+agent = ReviewAgent.create(persistence: store)
+agent.invoke(text) # the Runtime still owns this incarnation afterwards
+```
+
+After, the application declares the ownership boundary once:
+
+```ruby
+Phronomy::Agent.open_scope do |agents|
+  agent = agents.create(ReviewAgent, persistence: store)
+  agent.invoke_async(text)
+end
+```
+
+`open_scope` waits for a returned TaskResult and returns its resolved value (or
+raises the original exception). A plain block value is returned unchanged.
+It then attempts to unload every Agent it acquired. A Workflow can use
+`agents.create_async` or `agents.load_async` from EventLoop and compose their
+TaskResults. The outer application keeps the scope alive until the Workflow has
+finished. A scope is not serializable Workflow context.
+
+An existing application-owned Agent cannot be adopted by `scope.load`: that
+would give the scope permission to release someone else's object. The attempt
+raises `AgentBusyError`. Repeated load in the same scope returns its live instance,
+after checking class and Store compatibility. A listener cannot be replaced on
+an already live instance. Existing `Agent.load`/`get` lookup semantics remain;
+obtaining a reference does not extend its owning scope's lifetime.
+
+## Release contract
+
+`agent.unload_async` returns `TaskResult<Boolean>` and is EventLoop-safe.
+`agent.unload!(timeout: nil)` waits externally. Both preserve all durable state:
+root and context revisions, journal position, contents, history, metadata and
+lifecycle status. A closed Agent remains closed after reload.
+
+Release requires an exact live owner, no accepted operations or execution
+admission (including approval and recovery waits), and an idle durable execution
+ledger with no retention references. C04 interprets only the presence of opaque
+retention references; their owning domain decides when to remove them.
+
+Concurrent release requests share the pending handle. A successful release
+returns `true`; an already unloaded reference returns `false`. A wait timeout
+does not cancel the release. Store check failure rolls back the reservation and
+preserves the original error. Runtime shutdown closes admission and drains
+already accepted transition completion without creating a replacement Runtime.
+
+New operations cannot enter during release. Old Agent operations fail with
+`AgentUnloadedError` (`code: "agent.unloaded"`, `agent_id`); asynchronous methods
+return failed TaskResults. Immutable snapshots and `agent_id` remain usable.
+A later load creates a new instance and can bind a new listener. The old
+reference cannot mutate or release that new owner. Purged Agents keep their
+existing `AgentPurgedError` semantics.
+
+A concurrent `get` or `load` during release raises `AgentBusyError` immediately;
+it does not wait or create a second owner. Accepted operations make unload fail
+with Busy at its admission gate. In particular, unload inside an Agent terminal
+listener is Busy while that listener is executing. Exit the outer application
+scope after result delivery to release it. Existing immutable local-state reads
+remain available while Runtime shutdown is draining an incomplete transition;
+new execution and mutation admission stays closed.
+
+## Failure and cancellation
+
+Scope tracks materialization receipts before starting work and registers acquired
+Agents before returning them. Closure stops new acquisition and waits for the
+physical completion of accepted materialization, even when its handle was
+cancelled. Indeterminate durable create keeps the C04 recovery reservation and
+logs the Agent ID; it is never silently made creatable again.
+
+Scope does not cancel or wait for unjoined child execution as an implicit
+cleanup policy. An active Agent is retained and cleanup reports `AgentBusyError`.
+If the main operation failed, its same exception is preserved and secondary
+cleanup failures are logged with Agent IDs. Logger failure cannot replace it.
+If the main operation succeeded, failed cleanup raises `Agent::ScopeCleanupError`
+(`code: "agent.scope_cleanup_failed"`). `result` preserves the successful value;
+`failures` is an array of `{agent_id:, error:}` with the original exceptions.
+All acquired Agents are attempted. No automatic retry, purge, or retention
+removal is performed.
+
+## Responsibility and ordering
+
+- C04 owns scope receipts, exact incarnation identity, operation admission,
+  busy/retention rules, invalidation and cleanup errors.
+- C07 supplies the existing transaction boundary. C04's Agent Store supplies
+  `assert_idle!`, `guard_agent!` and retention reads; neither Persistence nor
+  physical Storage gains incarnation release policy.
+- C13 supplies existing TaskResult and physical-completion contracts. It gains
+  no scope membership, Agent busy rules or unload states.
+- Engine supplies existing worker execution, serial EventLoop delivery and
+  shutdown participation. It gains no Agent-specific states.
+- The operation lease and release reservation share the C04 ownership mutex.
+  No Store transaction, Runtime call, application callback or blocking wait runs
+  under that mutex. Accepted runner continuations use C04 internal snapshots;
+  callbacks initiating a new public operation must acquire a new lease.
+- Agent operation completion is distinct from cancelling its public handle.
+  C04 acknowledges release after domain terminal/listener delivery and physical
+  worker completion. A queued or physically running cancelled operation still
+  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.
+
+This is P5 (core). P6 migrates application examples and performs cross-repository
+acceptance against the published or pinned candidate core.

data/docs/architecture/dx05-workflow-task-state.md

@@ -0,0 +1,134 @@
+# DX05-D: Workflow-owned asynchronous task states
+
+Status: unreleased Beta implementation. Based on DX05-A core `c673c958c`.
+
+## Problem and intended application boundary
+
+A Workflow application describes which operation a stage starts, how its result
+changes business state, and where that state goes next. Repeating callbacks,
+completion events, error envelopes and state-entry identifiers obscures those
+choices. Workflow already owns the live execution and state-entry lifetime, so it
+can own this correlation without knowing how an Agent, Tool or LLM runs.
+
+The business flow is preserved. Failure, cancellation, stale-result and delivery
+semantics become explicit and stronger; this is not a claim that every failure
+path of the previous manual recipe was equivalent.
+
+## Before and after
+
+Previously, each state manually arranged delivery (simplified successful path):
+
+```ruby
+workflow = nil
+workflow = Phronomy::Workflow.define(AnswerState) do
+  initial :asking
+  state :asking
+  entry :asking, ->(state) {
+    id = state.workflow_instance_id
+    agent.invoke_async(state.question).on_complete do |value, error|
+      workflow.signal(workflow_instance_id: id, event: :answer_ready,
+        payload: {value: value, error: error})
+    end
+    state
+  }
+  transition from: :asking, on: :answer_ready, to: :__finish__,
+    action: ->(state, event) {
+      raise event.payload[:error] if event.payload[:error]
+      state.merge(answer: event.payload.fetch(:value).fetch(:output))
+    }
+end
+```
+
+That snippet also needs rejection handling and entry-specific guards for safe
+reentry. The application now writes only the operation and successful update:
+
+```ruby
+workflow = Phronomy::Workflow.define(AnswerState) do
+  initial :asking
+  task_state :asking,
+    start: ->(state) { agent.invoke_async(state.question) },
+    apply: ->(state, result) { state.merge(answer: result.fetch(:output)) }
+  transition from: :asking, to: :__finish__
+end
+```
+
+`start` receives an isolated context snapshot, including current phase and
+Workflow identity. It must return a `Phronomy::TaskResult` promptly. It must not
+perform blocking I/O or wait for another Task. Use `Blocking.call_async` for real
+blocking work. `apply` receives the current context and successful value, runs
+briefly on EventLoop, and returns the same context type or nil. Normal transition
+guards run after `apply`. Nil means no context replacement, not failure.
+
+A task state may have ordinary entry/exit actions and external transitions.
+Leaving it abandons observation of its source. Declaring the same state as both
+`state`/`wait_state` and `task_state` is rejected. Ordinary entry/transition actions
+still cannot return a TaskResult. Business signals keep their existing API.
+
+## Contract ownership
+
+| Owner | Responsibility |
+|---|---|
+| C02 Workflow | Task-state definition; live execution and state-entry reception; once-only consumption; success application, failure/cancellation classification; stale-result and queued-progression rejection; restart policy |
+| C13 Execution | Thread-safe TaskResult notification and cancellation subscription mechanisms |
+| I07 Workflow runtime binding | Connect C02 decisions to the existing FSM, owner EventLoop and owner Runtime timer/shutdown services |
+| Engine | Generic event/session delivery and lifecycle; no task-state or Agent policy is added |
+| C04 Agent and application | Agent execution, business transformation/fallback, child cancellation policy and producer lifetime |
+
+C02 uses its execution-environment port and receives an injected session
+connection. It does not select Runtime or depend on I07. `WorkflowTaskSession`
+in I07 adapts the generic FSMSession. Engine source is unchanged.
+
+A revocable C02 reception is created before `start`. Source callbacks retain only
+that reception. Closing it drops source and registry references. Completion is
+sent to the originating registry under an opaque execution owner token, never
+rerouted by a durable Workflow ID. Receiver-side validation checks the current
+entry and consumes once. Exits, reentry, cancellation and terminal decisions
+revoke it. Queued automatic progression also carries an entry-specific key:
+an external transition between result application and automatic dispatch cannot
+advance a later entry. These private messages are not public business signals.
+
+## Outcomes and lifetime
+
+| Condition | Caller-visible result |
+|---|---|
+| Start throws, source fails, or apply throws | Workflow fails with the same error object |
+| Source status is `cancelled` | Workflow TaskResult is cancelled with the source error |
+| Source status is `failed` with a CancellationError | Remains failed; class alone does not imply cancellation |
+| Explicit parent token cancellation/deadline | Cancel Workflow observation; do not implicitly cancel the source |
+| Old or duplicated source notification | Ignore; no application or retry |
+| Current completion delivery rejects/throws | Fail on the owner; if owner delivery is wholly unavailable, settle observation only and retain admission until shutdown cleanup |
+| Runtime shutdown while waiting | Settle observation and revoke subscriptions; no claim that child work physically stopped |
+| Known durable terminal result | Use existing save/readback classification and release rules |
+| Unknown durable terminal result | Fail the observation while retaining recovery-required ownership |
+
+Cancellation is serialized on the owning EventLoop. Once terminal persistence
+has begun, its existing durable barrier remains authoritative; later cancellation
+does not reverse a committed or uncertain terminal decision. A source passed to
+the state has an independent lifetime. Applications explicitly pass cancellation
+controls to children when desired; they own Agent release and side effects.
+
+This API creates no thread/worker for logical waits. Actual I/O and existing
+tracing or checkpoint work may still use the bounded pool. Expected business
+failures may be transformed into ordinary values through TaskResult composition.
+The API does not infer retry, fallback, durable child execution or delivery ACKs.
+
+## Persistence and restart
+
+Normal completion and ordinary `wait_state` halts use existing Workflow
+checkpoints. Resuming an ordinary wait into a new task state is supported. Pending
+TaskResults, callbacks and entry keys are process-local and are never serialized.
+Restoring a snapshot whose phase is a task state raises
+`Phronomy::WorkflowTaskResumeError` (C02, subclass of `Phronomy::Error`, code
+`workflow.task_resume_unsupported`) before running its start callback. The
+application must reconcile that operation explicitly instead of automatically
+repeating external side effects. F01 durable child execution remains separate.
+
+## Verification
+
+The new task-state regression suite covers immediate and delayed results,
+repeated entry, old success/failure/cancellation, duplicate callbacks, external
+transition races, rejected guards, delivery failure, shutdown, source/parent
+cancellation, owner Runtime selection, retained-reference revocation, strict
+callback result types, normal durable halt/resume, restart rejection and unknown
+durable outcomes. Existing Workflow, TaskResult, API and executable-documentation
+tests remain active. Examples 01/03/04/07/14/20/25/26 use the new API.