phronomy 0.22.0 → 0.24.0

data/docs/features.md

@@ -18,9 +18,9 @@ for production deployments.
 | Feature | Stability |
 |---|---|
 | **Workflow** — Stateful, branching workflows with `wait_state` and explicit events | Stable |
-| **Agent** — Stateful ReAct-style agents with stable `agent_id`, persistence-backed execution state, canonical history, guardrails, and conversation context | Stable |
+| **Agent** — Stateful ReAct-style agents with stable `agent_id`, one mutable live owner per Runtime, persistence-backed execution state, canonical history, and conversation context | Stable |
 | **Tool authoring façade** — `Phronomy::Tool::Base` is the public authoring name for the existing Capability base class; the legacy namespace remains compatible | Beta |
-| **Unified Persistence** — One durable backend abstraction for Agent state and Workflow `workflow_states`; live Agent/Workflow state remains owned by the active instance/session between durable commits; custom backends implement the documented Backend SPI and repository/transaction semantics | Beta |
+| **Unified Persistence** — One durable backend abstraction for Agent state and Workflow `workflow_states`; live Agent/Workflow state remains owned by Runtime/session authority between durable commits; custom backends implement the documented Backend SPI and repository/transaction semantics | Beta |
 | **LLMAdapter SPI** — `Phronomy::LLMAdapter::Base#complete` / `#stream` define the Beta call-adapter extension boundary; Phronomy owns async/offload wrapping | Beta |
 | **Before-Large-Language-Model (LLM) Input Hook** — Three-tier per-call LLM input customization via `before_llm_input` and `LLMInputPatch` | Stable |
 | **Context Management** — Journal + Context Policy + per-LLM-call Manifest with token-budget-aware selection and protocol-safe Tool Call / Tool message dependencies | Stable |
@@ -28,9 +28,18 @@ for production deployments.
 | **`PromptInjectionFilter`** — Built-in pattern-based prompt-injection filter | Beta |
 | **Capability redaction/result-size controls** — `redact_params` and `max_result_size` | Beta |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
-| **Tracing** — Pluggable span-based observability | Stable |
+| **Tracing** — Pluggable logical-operation span observability with bounded automatic coverage | Stable |
 | **Error Taxonomy** — Provider errors translated to Phronomy transport/authentication/rate-limit/context errors | Beta |
 
+Agent definition lineage is separate from Agent instance identity. A named
+concrete Agent may declare `agent_definition version: N`; when `id:` is omitted,
+its fully-qualified Ruby class name is the stable `agent_definition_id`.
+Applications may keep a lineage independent of Ruby constant naming with an
+explicit `id:`. Concrete subclasses declare their own definition revision
+rather than implicitly inheriting the parent revision. The Stable
+`before_llm_input` context exposes the semantic revision as
+`agent_definition_version`.
+
 ## Knowledge and integration
 
 | Feature | Stability |
@@ -47,10 +56,12 @@ for production deployments.
 
 | Feature | Stability |
 |---|---|
-| **EventLoop** — Runtime-owned event-driven execution core shared by Agent, ToolInvocation, Workflow, and MultiAgent sessions | Beta |
-| **Workflow durable admission** — Durable `thread_id` ownership is held by a Runtime-only `fsm_session_id` from load through terminal save | Beta |
+| **EventLoop** — Runtime-owned event-driven execution core shared by Agent, ToolInvocation, Workflow, and MultiAgent sessions; single writer for Phronomy-managed live Agent execution state | Beta |
+| **Agent execution result authority** — Session-local routing plus current FSM state and purpose-specific semantic IDs (`llm_call_id`, `tool_invocation_id`) reject stale async results | Beta |
+| **Agent live ownership/admission** — Runtime owns one mutable live Agent per `agent_id`; EventLoop rejects competing same-Agent top-level executions while suspension retains the logical execution slot; Persistence admission remains durable defense | Beta |
+| **Workflow durable admission** — Same-process admission is keyed by durable `workflow_instance_id` from pre-hydration admission through the durable terminal/halted save barrier; admission-owner representation is Runtime-internal | Beta |
 | **`invoke` / `invoke_async`** — Blocking and non-blocking Agent/Workflow entry points | Stable |
-| **Agent async events** — `invoke_async(..., on_event:)` and `stream_async(..., on_event:)`; streaming additionally emits `:token` | Beta |
+| **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 |
@@ -58,7 +69,7 @@ for production deployments.
 | **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 |
-| **InvocationContext** — Explicit correlation/cancellation/deadline context for Agent and Workflow invocations | Beta |
+| **InvocationContext** — Explicit cancellation/deadline/policy plus observability-correlation context for Agent and Workflow invocations | Beta |
 | **Metrics** — OffloadPool active/queue/abandoned metrics plus EventLoop queue/lag metrics | Beta |
 | **Runtime lifecycle** — Runtime-owned EventLoop and terminal `Runtime#shutdown` | Beta |
 
@@ -67,13 +78,18 @@ for production deployments.
 | Feature | Stability |
 |---|---|
 | **Workflow asynchronous pattern** — Start async work, return immediately, and continue through `Workflow#signal` | Beta |
-| **Multi-agent** — Agent-as-Tool and hub-and-spoke handoff routing | Beta |
+| **Durable Agent Handoff** — `Agent::Handoff` and `Agent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
 | **GeneratorVerifier** — Generator-Verifier loop with injectable prompts/parsers | Beta |
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |
 | **SharedState** — Peer-agent shared-state coordination | Experimental |
-| **Human-in-the-loop approval** — Suspension and approval/resume of Tool requests on the same live Agent/Activation owner | Beta |
-| **`tool_approval_policy`** — Application-defined allow/approve/reject policy | Beta |
+| **Human-in-the-loop approval** — durable suspension publishes `:approval_required` through the Agent listener; `approve` / `approve_async` resumes the same logical `execution_id` with a fresh FSMSession incarnation | Beta |
+| **`tool_approval_policy`** — Application-defined allow/approve/reject policy using a value-only `ApprovalEvaluationRequest` without live Agent/Tool references | Beta |
+
+For Handoff, Application `HandoffPolicy` controls what may cross the Source/Target
+boundary. Transferred Handoff Context is immutable request-scoped material rather
+than automatic Target Journal/Knowledge adoption. Target Context Policy still
+selects what enters each individual Target LLM call.
 
 ## Public API boundary
 
@@ -100,12 +116,16 @@ extension contracts are deliberate exceptions to the ordinary
 application-facing interpretation of `@api public`: they are compatibility
 contracts for implementers. Extension implementations must not depend on Runtime
 private execution objects such as EventLoop/FSMSession/OffloadPool operation
-records.
+records or EventLoop Agent execution entries.
 
 `Phronomy::StateStore` is no longer a public backend abstraction. Workflow
 durability is provided through `Phronomy::Persistence#workflow_states`; see the
 0.19 migration guide when upgrading code that used `state_store:`.
 
+For current architecture/authority boundaries, start at
+[Architecture](architecture.md). Archived historical design material is not a
+current compatibility contract.
+
 ## Advanced and internal APIs
 
 | Feature | Stability |
@@ -120,3 +140,37 @@ durability is provided through `Phronomy::Persistence#workflow_states`; see the
 
 For runtime ownership and the distinction between public lifecycle APIs and
 private execution machinery, see [Runtime and concurrency](runtime-and-concurrency.md).
+
+### Durable semantic coordination (V2 revision 2)
+
+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.
+`Orchestrator#resume(execution_id)` continues retained parent coordination.
+
+`TeamCoordinator` requires `team_definition id:, version:` and provides
+`create`, `load`, `get`, `resume`, `executions`, `result` and scoped `cancel`.
+Team tasks, worker assignments, exact child identities and aggregate outcomes
+are durable facts. Workers still execute sequentially through the existing Agent
+engine. `schedule` and `aggregate` must be pure and replay-safe; aggregate returns
+canonical JSON data. Default assignment results have string keys and error data
+contains class/message strings. Arbitrary Ruby objects are not durable results.
+
+`Persistence#execution_result` / `team_execution_result` read exact results;
+`list_executions` / `list_team_executions` discover retained active and terminal
+runs by known owner ID. Reads do not load Runtime owners or deliver callbacks.
+The cursor is an exclusive lexical execution ID and limit must be positive.
+Retention and request correlation remain Application/backend policy.
+
+Guarantee: confirmed outcomes are reused, unfinished work keeps its semantic ID,
+and external outcome uncertainty uses Agent Recovery. For F1/F4 this is
+conditional on a conforming retained Persistence domain and compatible current
+wiring. InMemory provides transaction/CAS semantics but is not durable disk storage.
+Callbacks/streams/Tasks are Runtime observations; there is no restart-spanning
+notification outbox, ACK, synthetic fan-out execution or external exactly-once
+claim. See [the migration](migrations/durable-semantic-coordination-v2.md).
+
+`Persistence#handoff_result(source_execution_id)` also resolves the exact Handoff
+turn read-only, including a current absent-but-reserved Target, without graph or
+Agent hydration. Purging an idle main Agent removes its Handoff anchor; pending
+coordination rejects purge rather than discarding its reservation.

data/docs/getting-started.md

@@ -100,7 +100,7 @@ result = agent.invoke("What is my name?")
 puts result[:output]
 ```
 
-Load the same Agent again when the same Persistence backend is available:
+Resolve the same logical Agent when the same Persistence backend is available:
 
 ```ruby
 agent = ResearchAgent.load(
@@ -111,8 +111,24 @@ agent = ResearchAgent.load(
 agent.invoke("Continue our previous discussion.")
 ```
 
-`load` is the hydration boundary. While that Agent instance is live, the
-instance and its active `AgentExecutionActivation` own the current logical state.
+A Runtime has at most one mutable live Agent object for an `agent_id`. If the
+Agent is already live, repeated `load` returns that exact Ruby object and does
+not reload Persistence. If it is not live, `load` hydrates the durable Agent
+once. Loading an ID that does not exist durably raises
+`Persistence::NotFoundError`.
+
+Use `get` when only a process-local lookup is wanted:
+
+```ruby
+live = ResearchAgent.get("research-session-42")
+```
+
+`get` never reads Persistence and returns `nil` when this Runtime has no live
+owner. `new` and `create` are creation operations, not get-or-load operations;
+they raise `AgentAlreadyExistsError` if the requested identity already exists.
+
+While the Agent is live, it owns its current AgentRoot/Journal view and
+Runtime/EventLoop owns process-local identity/admission/execution authority.
 Phronomy persists snapshots at defined durability boundaries but does not reload
 mutable Agent/Execution/Journal state before every LLM or Tool step. A conflicting
 external durable write is surfaced as `Persistence::ConflictError` rather than
@@ -127,8 +143,10 @@ agent.clear_knowledge!
 agent.reset_context!
 ```
 
-`purge!` is different: it permanently removes the Agent and persisted execution
-history from the configured Persistence backend.
+`purge!` is different: it explicitly destroys the logical Agent and removes its
+persisted execution history from the configured Persistence backend. After a
+successful purge the old Ruby object is permanently unusable; the textual
+`agent_id` may then be used to create a new logical Agent.
 
 ## Sync and async Agent APIs
 
@@ -142,18 +160,25 @@ task = agent.invoke_async("Hello")
 result = task.wait_result
 ```
 
-Both `invoke` and `invoke_async` can receive public Agent events through either
-an `on_event:` listener or a block. A block is convenient when the listener is
-local to the call:
+Public Agent events belong to the live Agent Runtime incarnation. Register
+the listener when the Agent is materialized, not on each invocation:
 
 ```ruby
-task = agent.invoke_async("Hello") do |event|
-  puts event.payload[:output] if event.type == :done
-end
+agent = ResearchAgent.load(
+  "research-session-42",
+  persistence: persistence,
+  on_event: ->(event) {
+    puts event.payload[:output] if event.type == :done
+  }
+)
+
+task = agent.invoke_async("Hello")
 ```
 
-Use `on_event:` when the listener already exists as a callable. Do not provide
-both `on_event:` and a block to the same invocation.
+`new`, `create`, and `load` also accept an equivalent listener block.
+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 work. Logical lifecycle progress is driven by EventLoop/FSMSession;
@@ -163,45 +188,52 @@ OffloadPool. Both paths expose completion as a `Task`.
 `Task#wait_result` is for an external caller. Do not block EventLoop waiting for
 a Task that can only complete through that same EventLoop.
 
-Streaming follows the same split:
+Streaming uses the same Agent-incarnation listener:
 
 ```ruby
-agent.stream("Explain the design") do |event|
-  puts event.payload if event.type == :token
-end
-```
+agent = ResearchAgent.new(
+  on_event: ->(event) {
+    puts event.payload if event.type == :token
+  }
+)
 
-```ruby
-task = agent.stream_async("Explain the design") do |event|
-  puts event.payload if event.type == :token
-end
+agent.stream("Explain the design")
+task = agent.stream_async("Explain another design")
 ```
 
-Agent event callbacks execute on EventLoop and therefore should return quickly.
+`stream` / `stream_async` require an Agent event listener because event
+delivery is their public streaming channel. Agent event callbacks execute on
+EventLoop and therefore should return quickly.
 
 ## Human-in-the-loop approval
 
-A Tool requiring approval can suspend an Agent invocation. Resume it with the
-approval request identifier returned by the suspension result.
-
-At a top-level synchronous boundary:
+A Tool requiring approval suspends the durable logical execution without
+settling the original execution Task. Approval notification is delivered
+through the same Agent listener as `:approval_required`:
 
 ```ruby
-result = agent.invoke("Perform the requested protected action")
+agent = nil
+agent = ResearchAgent.new(
+  on_event: ->(event) {
+    next unless event.type == :approval_required
+
+    request = event.payload.fetch(:request)
+    agent.approve_async(
+      request.execution_id,
+      approval_request_id: request.id,
+      approved: true
+    )
+  }
+)
 
-if result[:suspended]
-  request = result[:approval_request]
-  result = agent.approve(
-    result[:execution_id],
-    approval_request_id: request.id,
-    approved: true
-  )
-end
+result = agent.invoke("Perform the requested protected action")
 ```
 
-From an EventLoop callback, use `approve_async` rather than blocking EventLoop.
-Approval resume continues the same live Agent instance, Activation, and
-AgentInvocation; it is not an Agent reload boundary.
+Use `approve_async` inside the EventLoop callback; synchronous `approve` is
+for an external thread that already has the durable approval identifiers.
+Approval resume continues the same live Agent instance and AgentInvocation;
+Runtime resolves that process-local owner through EventLoop rather than through a
+shared Activation object. It is not an Agent reload boundary.
 
 ## Workflow basics
 
@@ -237,16 +269,16 @@ workflow = Phronomy::Workflow.define(
   transition from: :finalize, to: :__finish__
 end
 
-state = workflow.invoke({draft: ""}, config: {thread_id: "doc-1"})
+state = workflow.invoke({draft: ""}, config: {workflow_instance_id: "doc-1"})
 final = workflow.send_event(state: state, event: :approve)
 puts final.approved
 ```
 
-`Persistence#workflow_states` is the durable Workflow repository. `thread_id`
+`Persistence#workflow_states` is the durable Workflow repository. `workflow_instance_id`
 identifies the durable Workflow state and remains stable across resume. Each
 concrete Runtime execution receives a separate internal `fsm_session_id`; the
 application-level `session_id` remains ordinary caller/tracing metadata. Phronomy
-holds owner-aware admission for `thread_id` from durable load through terminal
+holds owner-aware admission for `workflow_instance_id` from durable load through terminal
 save so another local invocation cannot start from a stale snapshot while the
 current owner is still committing.
 
@@ -275,7 +307,7 @@ class AnswerContext
 
   field :question, type: :replace, default: ""
   field :answer,   type: :replace, default: nil
-  field :thread_id, type: :replace, default: nil
+  # workflow_instance_id is framework-owned metadata; do not declare it as a field.
 end
 
 class ResearchAgent < Phronomy::Agent::Base
@@ -293,13 +325,13 @@ workflow = Phronomy::Workflow.define(AnswerContext) do
   state :done
 
   entry :asking, ->(ctx) {
-    thread_id = ctx.thread_id
+    workflow_instance_id = ctx.workflow_instance_id
 
     my_agent.invoke_async(ctx.question) do |event|
       next unless event.type == :done
 
       workflow.signal(
-        thread_id: thread_id,
+        workflow_instance_id: workflow_instance_id,
         event: :answer_ready,
         payload: {answer: event.payload[:output]}
       )

data/docs/migrations/0.19.md

@@ -98,8 +98,14 @@ A live Agent instance now remains the logical owner of its mutable state after
 hydration. Phronomy no longer re-loads mutable AgentRoot/AgentExecution/Journal
 state at each LLM boundary just to obtain freshness.
 
-Approval resume continues the same live Agent/Activation and is performed through
-the Agent instance APIs:
+Current Runtime releases keep one process-local mutable Agent owner per `agent_id`
+in a Runtime-owned registry. Repeated `load` returns that exact owner without
+reloading durable state, and `get(agent_id)` performs only a process-local lookup.
+EventLoop separately owns same-Agent top-level execution admission and live
+execution progression; Persistence admission remains a durable integrity defense.
+
+Approval resume continues the same process-local live Agent owner and is performed
+through the Agent instance APIs rather than an Activation object:
 
 ```ruby
 agent.approve(...)
@@ -125,11 +131,12 @@ If the concrete Agent class is not known, use:
 agent = Phronomy::Agent::Base.live_for_execution(execution_id)
 ```
 
-`live_for_execution` resolves the Runtime-local Activation and returns its
-existing Agent instance. It does not accept `persistence:` and does not load a new
-Agent or Execution from Persistence. If the live Activation has been lost (for
-example after process restart), it raises `ExecutionRehydrationRequiredError`
-until durable execution rehydration is implemented.
+`live_for_execution` resolves the Runtime/EventLoop process-local owner and
+returns its existing Agent instance. It does not accept `persistence:` and does
+not load a new Agent or Execution from Persistence. If that live owner has been
+lost (for example after process restart), it raises
+`ExecutionRehydrationRequiredError` until durable execution rehydration is
+implemented.
 
 `execution_id` is not an authorization token. HTTP/API applications must still
 verify that the caller is allowed to act on the resolved Agent and approval