phronomy 0.22.0 → 0.24.0

data/docs/persistence-backends.md

@@ -23,10 +23,13 @@ Phronomy::Persistence synchronous Backend SPI
 Database / durable storage
 ```
 
-Persistence does not own live execution state. In particular, a backend must not
-persist or reconstruct the following as part of this SPI:
+Persistence does not own live Agent identity, top-level Runtime admission, or
+live execution state. In particular, a backend must not persist or reconstruct
+the following as part of this SPI:
 
-- `AgentExecutionActivation`;
+- Runtime Agent ownership-registry entries;
+- EventLoop Agent top-level admission entries;
+- EventLoop Agent execution-directory entries;
 - `AgentInvocation`;
 - `FSMSession`;
 - `Task` or callbacks;
@@ -41,7 +44,7 @@ contract.
 
 ## Required root surface
 
-A Persistence backend exposes five durable repositories:
+A Persistence backend exposes eight durable repositories:
 
 ```text
 contents
@@ -49,6 +52,9 @@ agents
 journals
 executions
 workflow_states
+handoff_states
+teams
+team_executions
 ```
 
 and two root operations:
@@ -63,7 +69,7 @@ persistence.assert_agent_watermark!(
 ```
 
 The object yielded by `transaction` is a transaction-scoped Persistence view. It
-must respond to all five repository accessors and
+must respond to all eight repository accessors and
 `assert_agent_watermark!`. It may be the Persistence instance itself, but SQL
 backends may instead yield an object bound to a checked-out connection or
 transaction session.
@@ -87,7 +93,7 @@ this requirement.
 
 All durable repositories must be able to participate in one atomic transaction
 domain. A transaction may change `contents`, `agents`, `journals`, `executions`,
-and `workflow_states` and then either commit all changes or roll them all back.
+`workflow_states`, `handoff_states`, `teams`, and `team_executions`, and then either commit all changes or roll them all back.
 
 This requirement deliberately does not claim exactly-once semantics after an
 indeterminate database/network failure. If the underlying database cannot tell
@@ -96,8 +102,9 @@ failure rather than pretending the outcome is known.
 
 ### `atomic_admission`
 
-This capability refers to **Agent execution admission**, not Workflow distributed
-locking.
+This capability is a **durable Agent execution integrity defense**. It is not the
+primary same-process Agent ownership/admission mechanism and it is not Workflow
+distributed locking.
 
 For one Agent, `executions.create_active` must atomically guarantee both:
 
@@ -110,9 +117,15 @@ no active/suspended execution already exists for agent_id
 A conflict with an existing active/suspended execution raises
 `Phronomy::AgentBusyError`.
 
-Workflow admission remains Runtime/process-local. Cross-process Workflow
-lease/fencing is an application/distributed-coordination concern and is not part
-of this Backend SPI.
+Within one process, Runtime/EventLoop admission is acquired before the initial
+Persistence operation and is the primary competing-execution exclusion
+mechanism. `atomic_admission` remains required as the durable second line of
+defense against stale paths, durable conflicts, and unsupported cross-process
+races. It must not be removed merely because Runtime admission exists.
+
+Workflow admission remains Runtime/process-local. Cross-process Agent or
+Workflow ownership/lease/fencing is a separate distributed-coordination concern
+and is not part of this Backend SPI.
 
 ### `optimistic_revision`
 
@@ -137,8 +150,10 @@ identity, duplicate-ID, or compare-and-swap conflicts.
 
 ### `Phronomy::AgentBusyError`
 
-An Agent already has an active or suspended execution and another execution
-cannot be admitted.
+A durable nonterminal Agent execution already exists and another durable
+execution record cannot be established. Phronomy also uses the same public error
+for a competing process-local top-level request rejected by Runtime/EventLoop
+before the backend is called.
 
 ### `Phronomy::Persistence::SerializationError`
 
@@ -202,6 +217,11 @@ def delete(agent_id)
 - returns `Phronomy::Agent::AgentRoot`, not a raw database Hash;
 - raises `NotFoundError` when missing.
 
+These repository operations are durable-storage primitives. The higher-level
+`Agent::Base.load` API first consults Runtime's process-local live ownership
+registry and does not call the repository when the requested Agent is already
+live.
+
 `save` atomically checks:
 
 ```text
@@ -252,13 +272,17 @@ def create_active(execution)
 def load(execution_id)
 def save(execution_id, expected_revision:, execution:)
 def list_active(agent_id)
+def list(agent_id, after: nil, limit: 100)
 def delete(execution_id)
 def delete_for_agent(agent_id)
 def assert_idle!(agent_id)
 ```
 
-`create_active` performs atomic Agent admission. A duplicate `execution_id`
-raises `ConflictError`; an already busy Agent raises `AgentBusyError`.
+`create_active` performs atomic **durable** Agent execution admission. A duplicate
+`execution_id` raises `ConflictError`; an already busy Agent raises
+`AgentBusyError`. Runtime/EventLoop has already acquired the process-local
+logical execution slot on the normal Phronomy path before this repository method
+runs.
 
 `load` returns `Phronomy::Agent::AgentExecution`, not a raw database Hash, and
 raises `NotFoundError` when missing.
@@ -278,17 +302,19 @@ A failed precondition raises `ConflictError`.
 `assert_idle!` is used inside transactions before Agent context/Knowledge changes
 and destructive operations. It must raise `AgentBusyError` if an active/suspended
 execution exists. A SQL implementation must make this check part of a consistency
-boundary that cannot race with Agent execution admission; a best-effort SELECT
-outside the transaction is not sufficient.
+boundary that cannot race with durable Agent execution admission; a best-effort
+SELECT outside the transaction is not sufficient. Process-local Runtime
+admission is an additional upstream coordination layer, not a replacement for
+this durable check.
 
 ## Workflow states repository
 
 Required surface:
 
 ```ruby
-def load(thread_id)
-def save(thread_id, expected_revision:, snapshot:)
-def delete(thread_id, expected_revision:)
+def load(workflow_instance_id)
+def save(workflow_instance_id, expected_revision:, snapshot:)
+def delete(workflow_instance_id, expected_revision:)
 ```
 
 `load` returns `nil` when no row exists. Otherwise it returns a Hash containing a
@@ -315,6 +341,37 @@ snapshot and revision. String or Symbol Hash keys are accepted by Phronomy:
 
 Caller mutation of a loaded snapshot must not mutate durable storage.
 
+### Workflow Runtime admission and terminal-save outcome
+
+Same-process Workflow admission is owned by Runtime/EventLoop, not by this
+repository. EventLoop acquires an opaque owner token for `workflow_instance_id`
+before mutable durable load/hydration, then binds a separately generated
+`fsm_session_id` only after the concrete FSMSession is constructed.
+
+A durable Workflow terminal/halt snapshot is saved through OffloadPool while the
+owning FSMSession remains nonterminal. The backend still implements only the
+synchronous `save` contract above; it does not post Runtime events or decide FSM
+state.
+
+Phronomy interprets terminal-save results by semantic certainty:
+
+```text
+known successful save
+  -> durable barrier may be crossed
+
+portable known failure / known not committed
+  -> barrier remains closed; Workflow error path
+
+arbitrary storage/transport failure whose commit outcome is not established
+  -> outcome unknown; barrier remains closed and Runtime fails closed
+```
+
+This distinction is independent of physical topology. A local backend can have
+an uncertain outcome, and a remote backend can return a definite optimistic
+conflict. Backends must therefore preserve meaningful portable errors when the
+contract establishes them, and must surface other storage/transport failures
+honestly rather than converting them into `ConflictError`.
+
 ### Workflow value serialization
 
 `WorkflowContext#to_h` may contain ordinary Ruby application values. The
@@ -414,6 +471,17 @@ Phronomy::Agent::AgentExecution.from_h(hash)
 String and Symbol top-level keys are accepted by these new execution/call codecs,
 which permits adapters to use parsed JSON without reimplementing constructors.
 
+The current canonical `JournalRecord` Hash does not contain `correlation_id`.
+Legacy durable Journal Hashes that still contain that key may be passed to
+`JournalRecord.from_h`; the legacy key is accepted and ignored. Backends must not
+synthesize or populate `correlation_id` for new canonical Journal records, and
+they are not required to eagerly rewrite existing durable rows solely to remove
+the old physical value.
+
+This is a targeted migration rule for the removed generic identity field. It does
+not establish a general unknown-field or long-term codec/schema-versioning
+policy.
+
 The canonical Hash representation is the Phronomy/domain boundary. A backend is
 free to map that representation to normalized SQL columns, JSON, or another
 storage format internally.
@@ -457,6 +525,9 @@ RSpec.describe MyPersistenceBackend do
   it_behaves_like "a Journal repository"
   it_behaves_like "an Execution repository"
   it_behaves_like "a workflow state repository"
+  it_behaves_like "a Handoff state repository"
+  it_behaves_like "a Team repository"
+  it_behaves_like "a Team execution repository"
   it_behaves_like "a Persistence backend"
 end
 ```
@@ -467,10 +538,12 @@ require wrappers only; the authoritative shared-example implementations live
 under `lib/phronomy/testing/persistence_contract/` so the core suite and external
 backends cannot drift through copied definitions.
 
-The generic suite verifies repository behavior, CAS semantics, admission,
-mutation isolation, and whole-backend transaction behavior. Database-specific
-concurrency/locking mechanisms remain backend integration-test concerns; the SPI
-specifies outcomes rather than a particular SQL locking strategy.
+The generic suite verifies repository behavior, CAS semantics, durable execution
+admission, mutation isolation, and whole-backend transaction behavior. Runtime
+same-process ownership/admission is tested separately because it is not a
+Persistence Backend SPI responsibility. Database-specific concurrency/locking
+mechanisms remain backend integration-test concerns; the SPI specifies outcomes
+rather than a particular SQL locking strategy.
 
 ## SQL implementation guidance
 
@@ -481,24 +554,40 @@ may use combinations of:
 - conditional `UPDATE ... WHERE revision = ?`;
 - row locks;
 - serializable/repeatable-read isolation where appropriate;
-- partial unique indexes for active Agent execution admission;
+- partial unique indexes for durable active Agent execution admission;
 - transaction-scoped checks for Agent revision + Journal head.
 
 Backend-specific database exceptions should be translated to the Phronomy error
 contract where their meaning is known.
 
-## Explicit non-goals
-
-This Backend SPI does not provide:
-
-- durable reconstruction of a lost Agent Activation;
-- serialization of Runtime objects;
-- cross-process Workflow execution exclusion;
-- exactly-once external Tool side effects;
-- automatic conflict reload/merge;
-- a generic serializer registry for arbitrary Workflow field classes;
-- an async Persistence API.
-
-For the architectural reasons behind these boundaries, see
-[ADR-014: Unified Persistence for Durable State](decisions/014-unified-persistence-durable-state.md)
-and [Runtime and concurrency](runtime-and-concurrency.md).
+## V2 coordination Backend SPI (clean break)
+
+Both `Persistence.new` and `build_transaction_view` require all eight raw
+repositories. Five-repository fallback is removed. Existing record formats remain
+`0.1`; three additional record types are `phronomy.handoff_state`,
+`phronomy.team_root`, and `phronomy.team_execution`. Backend index metadata is
+explicit and MUST NOT be reconstructed by parsing DurableRecord payloads.
+
+| Raw repository | Required operations and explicit metadata |
+|---|---|
+| `handoff_states` | `load(main_agent_id)`; `save(main_agent_id, expected_revision:, next_revision:, active_agent_id:, record:)`; `delete(main_agent_id, expected_revision:)` |
+| `teams` | `create(team_id:, team_revision:, record:)`; `load(team_id)`; `save(team_id, expected_revision:, next_revision:, record:)`; `delete(team_id)` |
+| `team_executions` | `create_active(team_execution_id:, team_id:, execution_revision:, record:)`; `load(id)`; `save(id, expected_revision:, next_revision:, team_id:, active:, record:)`; `list_active(team_id)`; `list(team_id, after: nil, limit: 100)`; `delete(id)`; `delete_for_team(team_id)`; `assert_idle!(team_id)` |
+| `executions` extension | `list(agent_id, after: nil, limit: 100)` for retained active and terminal records |
+
+Handoff starts at revision 1 with expected revision nil; later saves advance
+exactly one revision. Team roots and executions begin at revision 0. Team
+admission has the existing `AgentBusyError` contract for an already active owner;
+stale CAS/duplicate identity uses `ConflictError`. Missing Team/execution loads
+raise `NotFoundError`; absent Handoff state returns nil. Unavailable reads and
+codec errors must propagate separately.
+
+Lists sort IDs lexically, use an exclusive ID cursor, return at most the positive
+integer limit, include only the requested owner, and return immutable copies.
+Backends define retention; enumeration does not implement input correlation or
+request deduplication. Terminal-to-active rewrites are invalid.
+
+For F1, atomic commit does not imply a known response. Phronomy reads back the
+same intended ID/fact before advancing. A backend must provide authoritative
+reads/CAS; failure of readback is returned without new semantic work. No callback
+ACK/index is part of the SPI. Existing cross-process exclusion limitations remain.

data/docs/runtime-and-concurrency.md

@@ -8,24 +8,40 @@ the bounded `OffloadPool`.
 
 For the design rationale, see [ADR-010](decisions/010-cooperative-first-concurrency.md).
 Durable-state ownership is defined by
-[ADR-014](decisions/014-unified-persistence-durable-state.md).
+[ADR-014](decisions/014-unified-persistence-durable-state.md), with live Agent
+Runtime execution-state ownership refined by
+[ADR-024](decisions/024-event-loop-single-writer-agent-runtime.md) and process-local
+Agent identity/admission ownership defined by
+[ADR-025](decisions/025-process-local-agent-ownership-and-runtime-admission.md).
+Canonical Workflow instance identity is defined by
+[ADR-020](decisions/020-canonical-workflow-instance-identity.md).
+Concrete FSMSession incarnation identity and session-local Runtime routing are
+defined by [ADR-023](decisions/023-fsm-session-incarnation-identity-and-routing.md).
+Same-process Workflow admission ownership and durable terminal-barrier ordering
+are defined by
+[ADR-026](decisions/026-workflow-runtime-admission-and-durable-terminal-barrier.md).
 
 ## Runtime model
 
 ```text
 Runtime
+├─ Agent ownership registry
+│  └─ agent_id -> one mutable live Agent instance
 ├─ EventLoop (one control-plane operating-system Thread)
-│  └─ FSMSession
-│     ├─ Agent
-│     ├─ Workflow
-│     ├─ ToolInvocation
-│     └─ MultiAgent fan-out
-├─ process-local Agent ActivationRegistry
+│  ├─ FSMSession
+│  │  ├─ Agent
+│  │  ├─ Workflow
+│  │  ├─ ToolInvocation
+│  │  └─ MultiAgent fan-out
+│  ├─ Agent top-level admission
+│  │  └─ agent_id -> one nonterminal logical Execution admission
+│  └─ Agent execution directory
+│     └─ execution_id -> immutable live-state record
 ├─ OffloadPool (bounded operating-system Threads)
 │  ├─ private Operation records
 │  ├─ blocking input/output (I/O)
 │  ├─ central-processing-unit (CPU)-bound synchronous work
-│  └─ other long synchronous work
+│  └─ operation-specific durable Agent/Workflow work
 ├─ named OffloadPools
 └─ EventLoop-driven timers
 
@@ -44,12 +60,22 @@ A live Agent or Workflow owns its current logical state. `Persistence` is the
 last committed durable representation and recovery source; it is not reloaded at
 every semantic boundary.
 
-For Agents, the live owner consists of the Agent instance plus its current
-`AgentRoot`, hydrated Journal view, and `AgentExecutionActivation`. Mutable
-Agent/Execution/Journal state is not automatically reloaded before every LLM or
-Tool step. Durable writes use optimistic revision/position guardrails; an
-external writer that advances the durable base causes `Persistence::ConflictError`
-rather than automatic reload or merge.
+For active Agents, **EventLoop is the single writer of Phronomy-managed live
+execution state**. EventLoop owns a process-local execution directory keyed by
+canonical `execution_id`. Each directory value is immutable and is replaced on
+EventLoop when the current AgentExecution, RuntimeProjection, AgentInvocation, or
+owning FSMSession changes. The former mutex-protected
+`AgentExecutionActivation` / `ActivationRegistry` model is removed.
+
+`AgentInvocation` is the FSM-local mutable context and holds uncommitted Provider
+outcomes, Tool/runtime events, active Provider-call provenance, and callback
+failure state. These fields are advanced only by EventLoop-driven FSMSession
+handling; workers do not receive AgentInvocation as a mutable state authority.
+
+Mutable Agent/Execution/Journal state is not automatically reloaded before every
+LLM or Tool step. Durable writes use optimistic revision/position guardrails; an
+external writer that advances the durable base causes
+`Persistence::ConflictError` rather than automatic reload or merge.
 
 For Workflows, the current `WorkflowContext` and FSMSession own the active
 logical state. A durable Workflow hydrates once at invocation/resume and saves at
@@ -58,34 +84,198 @@ the halted/terminal boundary.
 Content-addressed `Persistence#contents` values are immutable. Fetching a known
 content reference is value materialization rather than mutable state refresh.
 
-## Workflow identities and durable admission
+## Process-local Agent identity ownership and admission
+
+`agent_id` identifies one logical Agent, not a reusable lookup key for independent
+mutable objects. One Runtime therefore publishes at most one mutable live Agent
+instance for a given `agent_id`. The Runtime-owned registry is an authority, not a
+cache, and reserves the identity before create/load materialization.
+
+The application-facing identity operations are distinct:
+
+```text
+new / create
+  create a new Agent; existing live or durable identity is an error
+
+load(agent_id, persistence:)
+  live -> exact same Ruby object, with no Persistence reload
+  durable-only -> hydrate and publish once
+  missing -> Persistence::NotFoundError
+
+get(agent_id)
+  live Runtime lookup only; missing -> nil
+```
+
+A live Agent is strongly owned for the Runtime lifetime even while idle and
+across sequential Executions. Execution completion does not evict it. Clean
+Runtime shutdown detaches old Agent objects so they cannot remain mutable beside
+a later Runtime owner. `purge!` is the explicit earlier destruction boundary: it
+invalidates the old object, deletes durable state, releases the process-local
+identity, and allows a later new Agent to reuse the textual ID.
+
+Live Agent ownership and top-level Execution admission are separate lifetimes.
+For one live Agent, EventLoop admits at most one nonterminal top-level Execution.
+Admission is acquired **before** the initial Offload/Persistence operation:
 
-Workflow execution keeps three identities separate:
+```text
+invoke
+  -> EventLoop Agent admission
+  -> Offload/Persistence executions.create_active
+  -> EventLoop live execution state
+```
+
+`preparing`, `active`, and `suspended` all retain the slot. A competing request is
+rejected with `AgentBusyError`; core does not promise automatic queueing. A
+known-successful durable terminal transition releases the slot. A known
+pre-durable failure may release it; an uncertain durable outcome remains
+fail-closed/recovery-required.
+
+`Persistence#executions.create_active`, optimistic revision, Journal position, and
+watermark checks remain required durable defenses. They do not become the
+primary same-process live ownership/admission mechanism and do not provide
+cross-process exclusion.
+
+## EventLoop single-writer and Offload result application
+
+Persistence repositories are synchronous, so durable work must remain off the
+EventLoop thread. The ownership rule is therefore not "run everything on
+EventLoop". It is:
+
+```text
+EventLoop
+  capture operation-specific immutable state
+      ↓
+OffloadPool
+  blocking I/O / CPU / operation-local calculation
+  durable commit
+      ↓ operation-specific result
+EventLoop
+  validate current authority
+  apply committed result to live state
+```
+
+Agent initial preparation, follow-up Manifest preparation, approval resume, and
+terminal commit use distinct command/result values. An Offload worker may commit
+Persistence but does not update the live Agent root, Journal view, current
+AgentExecution, RuntimeProjection, AgentInvocation runtime queues, or EventLoop
+execution directory.
+
+Completion callbacks are lightweight bridges that enqueue the result back to the
+EventLoop. If EventLoop no longer accepts the result, the callback does not fall
+back to direct live mutation.
+
+## Provider Call result authority
+
+Provider Call identity is purpose-specific semantic provenance. EventLoop
+allocates `llm_call_id` before transport begins and binds it to the Manifest used
+for that call.
+
+Provider completion and streaming chunks return through the owning FSMSession's
+EventSink and carry the `llm_call_id`. A result is applicable only when:
+
+- it still targets the current FSMSession incarnation;
+- the FSM is in the state that accepts that result; and
+- the AgentInvocation still owns the same active `llm_call_id`.
+
+A callback to an old FSMSession incarnation is dropped by session-local routing.
+A result with a stale `llm_call_id` is consumed without advancing the current
+FSM. Phronomy does not add a generic generation/correlation token as another
+result authority.
+
+Tool operations follow the same ownership direction. `tool_invocation_id` is the
+semantic Tool-operation identity, while FSMSession ID is Runtime routing identity.
+Tool authorization captures Agent identity and Tool description data as values on
+EventLoop before offload. The authorization worker receives no live Agent, Tool, or
+ToolInvocation reference. Application-owned approval/facts/requirement callables
+are explicitly classified behavior handles and receive a value-only
+`ApprovalEvaluationRequest`.
+
+Hash, Array, and String authorization command data is recursively copied/frozen.
+Phronomy-managed live domain objects are rejected from that value data. A complete
+value-type/serialization contract for arbitrary Application-owned opaque objects is
+deferred; such objects remain Application-owned and must be worker-safe.
+
+Worker authorization/execution outcomes return as values carrying
+`tool_invocation_id`; the Tool FSMSession consumes a mismatched semantic result
+without advancing its current state.
+
+## Approval suspension and live owner lookup
+
+Approval suspension retains the same process-local Agent and AgentInvocation but
+has no active owning FSMSession until resume. EventLoop retains the suspended
+execution entry.
+
+`Agent::Base.live_for_execution(execution_id)` resolves a read-only Runtime owner
+view and returns the existing Agent instance. `agent.approve_async(...)` routes to
+the same live coordinator. Neither operation reloads a replacement Agent or
+Execution from Persistence.
+
+A resume performs its durable approval transition through OffloadPool, applies
+the result on EventLoop, and then builds a **fresh** FSMSession incarnation.
+If the process-local owner no longer exists, durable continuation reconstruction
+is not implied; `ExecutionRehydrationRequiredError` is raised.
+
+## Workflow identities, admission, and durable terminal barrier
+
+Workflow runtime keeps identity and coordination responsibilities separate:
 
 ```text
 session_id
-  application session/correlation identity
+  application session/correlation metadata
 
-thread_id
-  durable Workflow identity and Persistence#workflow_states key
+workflow_instance_id
+  logical/durable Workflow identity and Persistence#workflow_states key
+
+admission owner token
+  opaque process-local Runtime coordination capability
 
 fsm_session_id
-  one Runtime FSMSession execution identity; generated again for each invoke/resume
+  one concrete Runtime FSMSession routing identity
+```
+
+EventLoop acquires the `workflow_instance_id` admission with a fresh opaque owner
+token **before** `workflow_states.load(workflow_instance_id)` is submitted. The
+token is not a domain identity and is never an Event target. After durable
+hydration, EventLoop constructs the concrete FSMSession and binds its fresh
+`fsm_session_id` to the existing admission for `Workflow#signal` routing.
+
+```text
+admit workflow_instance_id with owner token
+    ↓
+Offload workflow_states.load
+    ↓
+EventLoop hydrate / create FSMSession
+    ↓
+bind fsm_session_id for routing
 ```
 
-The application `session_id` is tracing/caller metadata and is not used for
-durable Workflow ownership. EventLoop registers active FSMs by `fsm_session_id`;
-durable Workflow admission is a separate owner map:
+A durable Workflow also keeps terminal persistence inside the FSMSession
+lifecycle. Logical halt/completion first enters a private
+`persisting_terminal` lifecycle condition; the FSMSession remains nonterminal
+while WorkflowRunner saves the terminal snapshot through OffloadPool. Only a
+known-successful save result returned to that same FSMSession permits
+`HALTED`/`COMPLETED`, admission release, and caller Task settlement.
 
 ```text
-thread_id -> owner_fsm_session_id
+RUNNING
+    ↓ logical halt/completion
+PERSISTING_TERMINAL
+    ├─ known success  -> HALTED / COMPLETED -> release
+    ├─ known failure  -> ERROR -> release
+    └─ outcome unknown -> RECOVERY_REQUIRED (fail closed)
 ```
 
-The owner is acquired before `workflow_states.load(thread_id)` and remains held
-until the halted/terminal `workflow_states.save(...)` completes. The admission map
-is process-local. Cross-process duplicate execution requires application-level
-distributed coordination; optimistic revisions detect stale terminal commits but
-do not prevent duplicate side effects before that conflict is detected.
+The FSMSession does not know whether Persistence is local, remote, SQL, HTTP, or
+networked. The Workflow persistence operation normalizes the result into
+`success`, `known_failure`, or `outcome_unknown`. Only known success crosses the
+durable barrier. If the backend/storage error does not establish non-commit,
+Phronomy treats the terminal outcome as uncertain rather than guessing.
+
+`recovery_required` prevents a fresh same-Workflow execution segment from being
+admitted, but ACS-13 does not claim restart-safe reconciliation; that remains
+ACS-15 work. The admission map itself is process-local. Cross-process duplicate
+execution requires the later coordination/fencing work; optimistic revisions
+remain durable conflict defense rather than distributed ownership.
 
 ## Tool execution modes
 
@@ -132,8 +322,7 @@ waiting at the same time.
 `Persistence` repositories expose synchronous operations. Framework lifecycle
 code must not perform potentially blocking durable reads/writes on EventLoop.
 Agent preparation/commit and Workflow hydrate/save operations are submitted to
-`OffloadPool`; completion continues through Task callbacks or explicit EventLoop
-events.
+`OffloadPool`; completion continues through explicit EventLoop events.
 
 A durable barrier may pause one logical lifecycle without blocking EventLoop.
 Persistence does not implement async repository variants and must not depend on
@@ -174,8 +363,9 @@ abandonment state.
 `Task#on_complete` registers an independent notification callback. Callback
 execution thread is not guaranteed. A callback may be delivered by an OffloadPool
 worker, a timer/cancellation caller, an EventLoop-related control path, or the
-thread that registers after settlement. Callbacks must be thread-safe and should
-complete quickly.
+thread that registers after settlement. Callbacks must therefore be thread-safe
+and should complete quickly. Framework lifecycle code normally converts worker
+completion into an explicit EventLoop event before applying live state.
 
 `Task#map` is application-level composition. A transformation exception settles
 the mapped Task as failed.
@@ -301,6 +491,10 @@ Workflow durable admission participates in EventLoop idleness: a Workflow whose
 FSMSession has ended but whose durable save is still in flight remains owned until
 that save completes and owner-aware admission is released.
 
+Suspended Agent execution owner entries are process-local continuation state and
+do not by themselves keep Runtime shutdown waiting. Runtime/process loss does not
+imply durable Agent continuation reconstruction.
+
 `Phronomy.reset_runtime!` exists primarily for test isolation and performs a real
 Runtime shutdown before resetting configuration.
 

data/examples/README.md

@@ -0,0 +1,13 @@
+# Phronomy examples
+
+Runnable application examples are maintained in the dedicated
+[`Raizo-TCS/phronomy-examples`](https://github.com/Raizo-TCS/phronomy-examples)
+repository.
+
+This repository intentionally does not keep a second runnable example set under
+`examples/`. Keeping one canonical sample repository avoids API drift between
+Phronomy's implementation/documentation and independently maintained copies of
+sample code.
+
+For framework-level executable behavior and regression coverage, use the specs
+under `spec/`. For application-oriented examples, use `phronomy-examples`.