phronomy 0.22.0 → 0.23.0

data/docs/decisions/README.md

@@ -0,0 +1,172 @@
+# Architecture Decision Records
+
+This directory contains Phronomy Architecture Decision Records (ADRs).
+
+The repository-wide architecture authority model is defined by
+[`017-design-authority-and-adr-governance`](017-design-authority-and-adr-governance.md).
+This index is the canonical navigation surface for ADR identity, status, and
+supersession relationships.
+
+## Canonical ADR identity
+
+The **canonical decision key** is the ADR filename basename, for example:
+
+```text
+012-canonical-execution-log-and-context-policy
+```
+
+The three-digit numeric prefix is an ordering/display number. It is not, by
+itself, a globally unique historical identifier because this repository
+already contains two legacy ADRs numbered `011`.
+
+Therefore:
+
+- new or modified normative material SHOULD link to the ADR file or use its
+  full canonical decision key;
+- the bare label `ADR-011` is ambiguous and MUST NOT be used to identify one
+  of the two legacy `011` decisions;
+- existing historical text is not rewritten merely to normalize old
+  references.
+
+## Status and authority
+
+ADR status has architecture meaning:
+
+- **Accepted** — normative architecture intent unless explicitly superseded.
+- **Amended** — normative architecture intent including its recorded
+  amendments.
+- **Superseded** — retained as decision history; non-normative for the
+  superseded scope.
+- **Proposed** — not normative until accepted.
+
+An Accepted ADR can temporarily disagree with implementation reality. That is
+an **architecture inconsistency**, not permission to silently treat whichever
+artifact is newer as authoritative. The inconsistency must be tracked and
+resolved explicitly.
+
+## ADR index
+
+| Canonical decision key | Status | Normative now? | Supersession / note |
+|---|---|---:|---|
+| [`001-rubyllm-as-provider-layer`](001-rubyllm-as-provider-layer.md) | Superseded | No | Superseded by [`027-llm-adapter-provider-boundary`](027-llm-adapter-provider-boundary.md); historical RubyLLM adoption rationale retained. |
+| [`002-workflow-context-immutability`](002-workflow-context-immutability.md) | Amended | Yes | `WorkflowContext#merge` remains new-instance semantics; direct generated field writers are EventLoop-owned guarded mutation APIs. |
+| [`003-event-loop-singleton`](003-event-loop-singleton.md) | Accepted | Yes | Current until explicitly superseded/refined. |
+| [`004-invoke-timeout-is-not-cancellation`](004-invoke-timeout-is-not-cancellation.md) | Superseded | No | Superseded by [`011-delegate-transport-policy-to-adapters`](011-delegate-transport-policy-to-adapters.md). |
+| [`005-static-knowledge-class-level-cache`](005-static-knowledge-class-level-cache.md) | Superseded | No | Superseded by [`013-journal-backed-knowledge-as-context-candidates`](013-journal-backed-knowledge-as-context-candidates.md). |
+| [`006-no-built-in-guardrails`](006-no-built-in-guardrails.md) | Superseded | No | Superseded by [`019-filter-contract-and-security-boundaries`](019-filter-contract-and-security-boundaries.md); historical minimal-built-in/Guardrail rationale retained. |
+| [`007-mcp-is-beta-stability`](007-mcp-is-beta-stability.md) | Accepted | Yes | Current. |
+| [`008-orchestrator-uses-os-threads`](008-orchestrator-uses-os-threads.md) | Superseded | No | Superseded by [`010-cooperative-first-concurrency`](010-cooperative-first-concurrency.md). |
+| [`009-state-store-abstraction`](009-state-store-abstraction.md) | Superseded | No | Superseded by [`014-unified-persistence-durable-state`](014-unified-persistence-durable-state.md). |
+| [`010-cooperative-first-concurrency`](010-cooperative-first-concurrency.md) | Accepted | Yes | Current until explicitly refined/superseded. |
+| [`011-build-context-as-single-llm-input-authority`](011-build-context-as-single-llm-input-authority.md) | Superseded | No | Superseded by [`012-canonical-execution-log-and-context-policy`](012-canonical-execution-log-and-context-policy.md). |
+| [`011-delegate-transport-policy-to-adapters`](011-delegate-transport-policy-to-adapters.md) | Accepted | Yes | Legacy duplicate numeric prefix; use the full canonical key. |
+| [`012-canonical-execution-log-and-context-policy`](012-canonical-execution-log-and-context-policy.md) | Accepted | Yes | Current Journal / Manifest / Context authority. |
+| [`013-journal-backed-knowledge-as-context-candidates`](013-journal-backed-knowledge-as-context-candidates.md) | Accepted | Yes | Current persistent Knowledge authority. |
+| [`014-unified-persistence-durable-state`](014-unified-persistence-durable-state.md) | Accepted | Yes | Durable-backend and live-owner/no-reload intent remains current; live Agent execution mutation is refined by ADR-024, same-process Agent identity/admission ownership by ADR-025, and same-process Workflow admission/terminal-barrier ordering by ADR-026. Workflow identity terminology is superseded by ADR-020, generic `InvocationContext` / Agent correlation semantics by ADR-021, and concrete FSMSession/Agent-Tool routing identity by ADR-023. |
+| [`015-tool-public-facade-and-rbs-boundary`](015-tool-public-facade-and-rbs-boundary.md) | Accepted | Yes | Current Tool façade / extension-SPI / RBS boundary. |
+| [`016-semantic-multi-agent-handoff`](016-semantic-multi-agent-handoff.md) | Accepted | Yes | Current semantic Handoff intent; runtime/context-transfer reconciliation is implemented and reflected in current architecture documentation. |
+| [`017-design-authority-and-adr-governance`](017-design-authority-and-adr-governance.md) | Accepted | Yes | Repository-wide architecture authority and ADR governance. |
+| [`018-durability-guarantees-and-failure-model`](018-durability-guarantees-and-failure-model.md) | Accepted | Yes | Repository-wide durability/concurrency/external-effect guarantee vocabulary and F0-F4/X0 failure model. |
+| [`019-filter-contract-and-security-boundaries`](019-filter-contract-and-security-boundaries.md) | Accepted | Yes | Current Filter transform/block and bounded PromptInjectionFilter/isolation boundaries; the follow-up review adds no fourth Context Filter call site and places semantic Context trust in Application ContextPolicy. |
+| [`020-canonical-workflow-instance-identity`](020-canonical-workflow-instance-identity.md) | Accepted | Yes | Canonical logical/durable Workflow identity and CG-01 clean-break migration. |
+| [`021-generic-agent-invocation-identity-removal`](021-generic-agent-invocation-identity-removal.md) | Accepted | Yes | Removes generic Agent/InvocationContext identity and canonical Journal `correlation_id`; CG-02 is closed, with targeted legacy durable-key read compatibility and no eager rewrite. |
+| [`022-agent-execution-parent-identity-and-runtime-routing-boundary`](022-agent-execution-parent-identity-and-runtime-routing-boundary.md) | Accepted | Yes | Canonicalizes Agent-owned Tool/approval logical parent as `execution_id`; CG-03a is reconciled, ADR-023 supplies incarnation routing, and ADR-024 supplies EventLoop result/live-state authority. |
+| [`023-fsm-session-incarnation-identity-and-routing`](023-fsm-session-incarnation-identity-and-routing.md) | Accepted | Yes | FSMSession-owned incarnation identity, session-local Agent/Tool/Multi-Agent routing, and stale-target drop remain current. Its transitional Workflow identity-reservation/admission bridge is superseded by ADR-026; Agent result authority is completed by ADR-024. |
+| [`024-event-loop-single-writer-agent-runtime`](024-event-loop-single-writer-agent-runtime.md) | Accepted | Yes | EventLoop is the single writer of Phronomy-managed live Agent execution state; removes Activation/ActivationRegistry and defines operation-specific Offload result application with current FSM + semantic-ID authority. |
+| [`025-process-local-agent-ownership-and-runtime-admission`](025-process-local-agent-ownership-and-runtime-admission.md) | Accepted | Yes | One mutable live Agent owner per `agent_id` per Runtime; EventLoop is the primary same-process top-level admission authority while Persistence admission remains durable defense. |
+| [`026-workflow-runtime-admission-and-durable-terminal-barrier`](026-workflow-runtime-admission-and-durable-terminal-barrier.md) | Accepted | Yes | EventLoop-owned opaque Workflow admission owner, admission-before-hydration ordering, and FSMSession-integrated durable terminal save barrier with fail-closed uncertain outcomes. |
+| [`027-llm-adapter-provider-boundary`](027-llm-adapter-provider-boundary.md) | Accepted | Yes | Phronomy-owned Provider-call extension boundary; RubyLLM is the default adapter/integration while current input materialization remains RubyLLM-specific. |
+
+## Legacy duplicate `011`
+
+The repository intentionally preserves both legacy files:
+
+```text
+011-build-context-as-single-llm-input-authority
+011-delegate-transport-policy-to-adapters
+```
+
+They are different decisions. The first is superseded by ADR-012; the second
+remains Accepted.
+
+They MUST NOT be silently renumbered. Their filenames are stable historical
+decision keys. New decisions may not introduce another duplicate numeric
+prefix.
+
+## Allocating a new ADR identifier
+
+For a new ADR:
+
+1. inspect all `NNN-*.md` files in this directory;
+2. allocate `max(existing numeric prefix) + 1`;
+3. format the number with three decimal digits;
+4. never fill an old gap and never reuse an existing prefix;
+5. if two unmerged changes select the same number, the change merged later
+   rebases and renumbers **only its new, not-yet-historical ADR**;
+6. add the ADR to this index in the same change.
+
+Existing ADRs are not renumbered merely because a numbering defect is later
+discovered. `016-semantic-multi-agent-handoff` is therefore preserved as-is.
+Under this rule the Design Authority decision is ADR-017.
+
+## Superseding or amending a decision
+
+Do not rewrite historical rationale into a fictional current history.
+
+When superseding an ADR:
+
+- add a new decision describing the new architecture;
+- update the old ADR's status/supersession note only as needed;
+- preserve the old rationale;
+- update this index in the same change;
+- use canonical decision keys/links where a numeric label would be ambiguous.
+
+Amendments are appropriate only when the original decision remains the same
+decision and the amendment can be understood without erasing the historical
+rationale. Materially different architecture should normally be a new ADR.
+
+## Architecture inconsistency process
+
+Architecture intent, public contract, and implementation reality are separate
+authority domains. If they disagree, do not resolve the conflict by recency.
+
+An unresolved architecture inconsistency must be recorded in the active
+repository work item (normally a GitHub issue or PR) with at least:
+
+```text
+Concern
+Normative authority
+Implementation / contract reality
+Conflict
+Resolution dependency
+Status: OPEN | DEFERRED | RESOLVING | RESOLVED
+Final resolution
+```
+
+Existing Workstream carry-forward (`CF-*`) and architecture-inconsistency
+(`AI-*`) registers are discovery/planning evidence, not normative architecture.
+During the current reconciliation program their unresolved contents are
+consolidated into named Architecture Change Sets (ACS) and Compatibility Gates
+(CG). A repository change that resolves such an item should identify the
+corresponding ACS/CG in its PR/commit rationale.
+
+A legacy carry-forward proposition is closed only by one of:
+
+- adoption into current source/public contract/current documentation;
+- an Accepted ADR;
+- explicit rejection/non-carry disposition; or
+- an open repository work item when the resolution is intentionally deferred.
+
+Working registers must not be copied wholesale into current architecture
+documentation as if they were normative decisions.
+
+## Relationship to explanatory architecture documentation
+
+ADRs record normative decisions. Explanatory architecture documents describe
+the current reconciled system but do not supersede ADRs merely by being newer.
+
+Current explanatory architecture starts at
+[`docs/architecture.md`](../architecture.md). Non-current design snapshots are
+segregated under `docs/archive/design/` and are non-normative. Explanatory
+architecture documents describe the reconciled current system but do not
+supersede ADRs merely by being newer.

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 |
+| **Semantic Multi-Agent Handoff** — `MultiAgent::Handoff` transfers active responsibility from an explicit Source Agent to a Target Agent, projects policy-bounded Context with provenance, keeps the Target active across user turns within the same Runtime/main-Agent lifetime, and does not claim durable continuation across Runtime reset | 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 |

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