phronomy 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ded63907d387d139d6f9017448da33707e9105ce45f49f246aac1aa764058434
-  data.tar.gz: 7e0125a2bec397563df61421474f0599e9773a9a6b6636f6949a5a858db8cb3d
+  metadata.gz: 8a9f9f2ab4acdb4e17edeb4e0b7f0b33660b7102e5b345c2bd8d411e6b0760de
+  data.tar.gz: 331265c52dfadbe4be8f85b9a48b35de384042664538f4fa74db0d34829e3b62
 SHA512:
-  metadata.gz: 694de5028ce07c43599b55de9380316f7210d9936a683924acd2d68c5f05348fb772fdc978726ef0782abf2d4d7c03146b32bf2eea3b78e7e54505161fe77c2c
-  data.tar.gz: 9d0217ddd076c29985d48eb1061cc92338054f54cf017c21425d263b056f22072c2657f3c06ef4db8142c08cf4b126b3d2c4c7cdc87409b718cc6cdcffdda2f4
+  metadata.gz: f3c7e0b15ede3129a2ac426ed86ebde36e353c664b5c64fc559878996ab6331b86f88c289e2f47179f0d1c58e91ec23c0c3d23060f066168c1a441e349dd534f
+  data.tar.gz: 527e858a300d3e8fb305782cdab29d6195b3836686df5b4d41a7abf8a40b584de8a8f0dcdab8ccd5b7b5dcfbcbf0c0dad45a7be2f092eae69c2c643ff69e9734

data/CHANGELOG.md

@@ -12,6 +12,31 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+### Unified Persistence and durable-state ownership
+
+#### Added
+
+- `Persistence#workflow_states` with optimistic revision checks for durable Workflow snapshots.
+- Runtime-local Agent Activation ownership; live `AgentExecutionActivation` values are no longer Persistence repositories.
+- `Agent::Base.live_for_execution(execution_id)` for resolving the current process's live owner Agent without reloading Agent or Execution state from Persistence.
+- Owner-aware Workflow admission keyed by durable `thread_id` and owned by a per-execution internal `fsm_session_id`.
+- ADR-014 and the 0.19 migration guide for the unified durable-state architecture.
+
+#### Changed
+
+- Live Agent instances now remain the authoritative logical-state owners after hydration. Context Policy and follow-up Manifest preparation use the Agent-local root, Journal view, and Activation state instead of reloading mutable Agent state for freshness.
+- `Phronomy.configuration.persistence` is the global durable backend for Workflows and for Agent `new`/`create` calls that do not explicitly inject another Persistence instance.
+- Agent durable writes use optimistic revision/Journal-position guardrails; conflicting external writes fail instead of being silently reloaded or merged.
+- Approval suspension/resume preserves the same live Agent/Activation/AgentInvocation. Approval remains an Agent-instance operation; callers with only an `execution_id` resolve the live owner with `Agent::Base.live_for_execution` (or the expected concrete Agent class) before calling `agent.approve` / `agent.approve_async`.
+- Workflow durable I/O runs outside EventLoop through OffloadPool, while `thread_id` admission remains owned until terminal/halted snapshot persistence completes inside the current Runtime. Workflow admission is process-local; optimistic revisions detect stale commits across processes but do not prevent duplicate execution or undo already-performed external side effects.
+- Workflow `thread_id`, Runtime `fsm_session_id`, and application `session_id` now have distinct responsibilities.
+
+#### Removed
+
+- `Phronomy::StateStore`, `StateStore::InMemory`, `Workflow.define(..., state_store:)`, `Configuration#state_store`, and per-invocation `config[:state_store]`.
+- `Persistence#activations`; ActivationRegistry is transient Runtime state.
+- Class-level `Agent::Base.approve` / `Agent::Base.approve_async` routing APIs and their caller-supplied `persistence:` argument; approval execution now goes through the resolved live Agent instance.
+
 ### OffloadPool execution model
 
 #### Changed

data/CONTRIBUTING.md

@@ -52,6 +52,36 @@ When adding, removing, or renaming a public method or class:
    bundle exec ruby scripts/api_snapshot.rb --write
    ```
 
+### `@api` classification vs Ruby visibility
+
+Phronomy's YARD `@api` annotation describes the compatibility boundary; it is
+not a synonym for Ruby's `public` / `protected` / `private` keywords.
+
+- `@api public` means consumers or extension implementers may rely on the
+  documented contract. Ruby visibility still follows the intended calling
+  model: ordinary methods may be public, subclass extension helpers may be
+  protected, and `initialize` remains Ruby-private while construction is
+  exposed through `.new`.
+- `@api private` means the method is internal and carries no public compatibility
+  promise. It may still be Ruby-public when Phronomy components need to call it
+  through an explicit receiver.
+- Ruby visibility is therefore not inferred from the `@api` annotation in
+  either direction.
+
+Run the annotation coverage guard when changing documented methods:
+
+```bash
+ruby scripts/check_api_annotations.rb
+```
+
+Ruby-public compatibility for the primary Stable/Beta product surface is
+protected by `scripts/api_snapshot.rb` and
+`spec/phronomy/api_compatibility_spec.rb`. Extension contracts whose calling
+model is protected/private should be protected by focused specs for that
+contract rather than by a repository-wide visibility inference rule.
+
+Do not change Ruby visibility merely to make it match an `@api` annotation.
+
 ---
 
 ## Architecture Decision Records

data/README.md

@@ -16,6 +16,7 @@ tracking `main` directly.
 ## Core concepts
 
 - **Agent** — stateful, persistence-backed LLM agent with canonical execution history.
+- **Persistence** — unified durable backend for Agent state and Workflow `workflow_states`.
 - **Workflow** — state-machine-driven application workflow with explicit events and wait states.
 - **Tool / Capability** — callable application capability exposed to an Agent.
 - **EventLoop + FSMSession** — the framework control plane for logical lifecycle coordination.
@@ -117,6 +118,7 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 - [MCP client](docs/mcp-client.md) — Model Context Protocol (MCP) integration and supported schema subset.
 - [Migration from 0.15-era APIs](docs/migrations/0.15.md).
 - [0.16 cleanup migration](docs/migrations/0.16.md).
+- [0.19 unified Persistence migration](docs/migrations/0.19.md).
 - [Architecture Decision Records](docs/decisions/) — design rationale and superseding decisions.
 - [CHANGELOG](CHANGELOG.md) — current development and recent release history.
 - [Changelog archive: 0.14.0 and earlier](docs/changelog/0.14-and-earlier.md).

data/docs/decisions/009-state-store-abstraction.md

@@ -1,6 +1,6 @@
 # ADR 009: StateStore Abstraction for Workflow Persistence
 
-**Status**: Accepted  
+**Status**: Superseded by ADR-014  
 **Date**: 2025-01  
 **Issue**: [#250](https://github.com/Raizo-TCS/phronomy/issues/250)
 

data/docs/decisions/014-unified-persistence-durable-state.md

@@ -0,0 +1,273 @@
+# ADR 014: Unified Persistence for Durable State
+
+**Status**: Accepted  
+**Date**: 2026-08-14  
+**Supersedes**: ADR-009
+
+---
+
+## Context
+
+Phronomy historically had two durable-state abstractions:
+
+- `Phronomy::Persistence` for Agent roots, Journals, content and executions;
+- `Phronomy::StateStore` for Workflow snapshots.
+
+At the same time, `Persistence` exposed `activations`, although
+`AgentExecutionActivation` contains live process state such as the active
+AgentInvocation, FSMSession, runtime projection, callbacks and uncommitted runtime
+facts. That state is not a durable database record.
+
+Keeping two durable backend abstractions makes SQL/database backends implement the
+same responsibility twice. Treating live Activations as Persistence also mixes
+process-local execution ownership with durable storage ownership.
+
+A second problem is state freshness. Re-reading mutable Agent records from
+Persistence before every semantic boundary makes the durable copy act as the
+source of truth even while a live Agent instance is executing. That makes
+ownership ambiguous and encourages implicit merge/reload semantics.
+
+Workflow runtime identity also needs to be distinct from its durable identity.
+`InvocationContext#session_id` already means application session metadata (for
+example a Rails session), while Workflow `thread_id` identifies durable Workflow
+state. Neither value is the identity of one concrete FSMSession execution.
+
+## Decision
+
+### Persistence is the only durable backend abstraction
+
+`Phronomy::Persistence` exposes the durable repositories:
+
+```text
+contents
+agents
+journals
+executions
+workflow_states
+```
+
+`Phronomy::StateStore` is removed without a compatibility adapter. Workflow
+persistence is configured with `persistence:` or
+`Phronomy.configuration.persistence` and stored through
+`Persistence#workflow_states`. Agent `new`/`create` also uses the global
+Persistence when no explicit backend is injected, so an application can select
+one durable backend for both domains. Explicit injection takes precedence.
+
+The `workflow_states` repository uses optimistic revision metadata:
+
+```ruby
+record = persistence.workflow_states.load(thread_id)
+# => nil or { snapshot: ..., revision: Integer }
+
+persistence.workflow_states.save(
+  thread_id,
+  expected_revision: record&.fetch(:revision),
+  snapshot: snapshot
+)
+```
+
+A stale expected revision raises `Phronomy::Persistence::ConflictError`. Upper
+layers do not automatically reload and merge after such a conflict.
+
+The normative contract for custom durable backends, including repository
+semantics, transaction requirements, capabilities, durable codecs, and the Agent
+watermark precondition, is documented in
+[`docs/persistence-backends.md`](../persistence-backends.md).
+
+### Activation is transient Runtime state
+
+`AgentExecutionActivation` is not part of the Persistence contract. Live
+Activations are held by a Runtime-local `Agent::ActivationRegistry`.
+
+Durable execution rehydration is a separate future capability. When no live
+Activation exists, approval resume raises
+`ExecutionRehydrationRequiredError`; the framework does not silently construct a
+new Agent and pretend that the process-local execution was recovered.
+
+### A live Agent instance owns its logical current state
+
+After hydration, the live Agent instance and its Activation are authoritative for
+mutable logical state:
+
+```text
+Agent instance
+├─ current AgentRoot
+├─ hydrated Journal/context view
+└─ active execution entry
+
+AgentExecutionActivation
+├─ current AgentExecution
+├─ runtime projection
+├─ Provider results
+├─ Tool/runtime events
+└─ active AgentInvocation / call state
+```
+
+Persistence is the last committed durable representation and recovery source.
+Normal LLM/Tool cycles do not re-read mutable AgentRoot, AgentExecution or Journal
+records merely to obtain freshness. Successful optimistic commits advance the
+local root/execution/Journals; failed revision checks surface a conflict.
+
+Before a next-LLM durable barrier, the backend verifies the live owner's Agent
+revision and Journal position as a durable watermark. This check is a precondition
+only: it does not return replacement state to the live Agent. If another writer
+has advanced either value, the barrier raises `ConflictError` and no Provider
+Call starts from the stale local owner.
+
+Content-addressed `contents` are immutable values and may still be dereferenced by
+content reference on demand. That is not a mutable-state refresh.
+
+Context Policy therefore sees the current local logical state rather than a
+Persistence readback. Runtime facts captured after a Persistence snapshot remain
+in the Activation and are eligible at the next semantic boundary.
+
+### Approval resumes the same owner
+
+An approval suspension retains the original Agent instance,
+`AgentExecutionActivation` and `AgentInvocation`. Instance-level
+`agent.approve` / `agent.approve_async` resume that live Activation.
+
+When an application has only an `execution_id`, it resolves the current process's
+live owner first:
+
+```text
+execution_id
+  -> Agent::Base.live_for_execution(...)
+  -> Runtime ActivationRegistry
+  -> live Activation
+  -> activation.agent
+```
+
+A concrete Agent class may call `MyAgent.live_for_execution(execution_id)` to
+also verify that the live owner is an instance of that class. The lookup does not
+load Agent or Execution state from Persistence. If the live Activation no longer
+exists, `ExecutionRehydrationRequiredError` is raised rather than silently
+rehydrating another owner.
+
+Approval remains an Agent-instance operation after lookup:
+
+```ruby
+agent = MyAgent.live_for_execution(execution_id)
+agent.approve_async(execution_id, approval_request_id: request_id)
+```
+
+### Workflow has three distinct identities
+
+The following identities must not be conflated:
+
+```text
+application session_id
+    caller/tracing identity, e.g. Rails session
+
+thread_id
+    durable Workflow identity / workflow_states key
+
+fsm_session_id
+    Runtime-only identity of one FSMSession invocation or resume
+```
+
+Each Workflow invocation/resume receives a fresh `fsm_session_id`. The EventLoop
+registers the session by that ID.
+
+For a Workflow with a durable `thread_id`, EventLoop also owns a separate
+admission table:
+
+```text
+thread_id -> owner_fsm_session_id
+```
+
+Admission is acquired before Persistence load and held through FSM execution and
+terminal snapshot save. Release succeeds only when the supplied
+`owner_fsm_session_id` is the current owner. A failed competing invocation can
+therefore never release another invocation's reservation.
+
+The admission table belongs to one Runtime and is process-local. It prevents
+competing execution of the same `thread_id` inside that Runtime, but it is not a
+distributed lease and is not shared by multiple Ruby processes, containers, or
+service replicas. Two processes may therefore execute the same durable
+`thread_id` concurrently if an application routes work that way.
+
+`workflow_states` optimistic revisions still detect stale/double commits between
+those processes. They do not prevent both executions from starting and cannot
+roll back external side effects already performed before one terminal save loses
+the revision race. CAS is therefore stale/double-commit protection, not
+distributed execution exclusion or duplicate-side-effect prevention.
+
+`fsm_session_id` is Runtime metadata. It is not an application Workflow field and
+is not stored in `workflow_states` snapshots.
+
+### Persistence I/O stays off EventLoop
+
+The Persistence repository contract remains synchronous. Persistence operations
+started by EventLoop-driven Workflow/Agent lifecycle code execute through the
+bounded OffloadPool. Completion is converted back into an EventLoop event where
+lifecycle ordering requires it.
+
+No worker waits synchronously for an FSMSession or Task that requires EventLoop
+progress.
+
+### Backend synchronization is an implementation detail
+
+`Persistence::InMemory` uses one shared `Monitor` for all durable repositories,
+including `workflow_states`. Workflow values retain StateStore-like deep-copy
+semantics and are kept outside the Marshal snapshot used by the existing Agent
+state container, while both remain inside the same transaction domain.
+
+A SQL backend should implement the same repository/transaction contract using DB
+transactions, isolation and optimistic revision constraints. Mutex/Monitor and
+Ruby object identity are not part of the public repository contract.
+
+## Consequences
+
+### Positive
+
+- Agent and Workflow durability share one backend configuration and transaction
+  abstraction.
+- Process-local Activation state is no longer presented as durable Persistence.
+- Active Agent ownership is explicit; Context Policy freshness no longer depends
+  on repeated mutable-state reloads.
+- Approval owner lookup and approval execution are separate: class-level lookup
+  resolves the existing live Agent, while approval remains an instance operation.
+- Revision conflicts are visible instead of being hidden by automatic merge.
+- Workflow durable identity is independent of one Runtime FSMSession execution.
+- Owner-aware Workflow admission closes the stale-load window during terminal
+  save inside one Runtime.
+- InMemory and future SQL backends can share one contract test suite.
+
+### Trade-offs
+
+- Removing `StateStore` is a pre-1.0 breaking change.
+- A process restart cannot resume an approval until durable Activation/FSM
+  rehydration is implemented separately.
+- Runtime Activation lookup and Workflow admission are process-local. Applications
+  requiring cross-process ownership or duplicate-execution prevention need a
+  separate routing/lease/fencing design.
+- Optimistic Workflow revisions can reject a stale commit but cannot undo
+  duplicate external side effects performed before that conflict is observed.
+- Applications that intentionally allow another process to edit the same live
+  Agent or Workflow must handle `ConflictError` and explicitly reload/reconcile.
+- `Persistence` implementations must provide `workflow_states` and optimistic
+  revision semantics.
+
+## Rejected alternatives
+
+### Keep StateStore as a compatibility facade
+
+Rejected. It preserves the duplicate durable-backend abstraction and makes future
+backend behavior harder to reason about.
+
+### Reload Agent state before every LLM call
+
+Rejected. It makes Persistence the live source of truth, creates implicit merge
+semantics and conflicts with Agent-instance ownership.
+
+### Use Workflow thread_id as FSMSession id
+
+Rejected. Durable identity and one Runtime execution have different lifetimes.
+It also makes owner-aware admission and application `session_id` terminology
+ambiguous.
+
+### Release Workflow admission by thread_id only
+
+Rejected. Cleanup from an invocation that failed to acquire admission could then
+release the real owner's reservation. Release is owner-aware by construction.

data/docs/features.md

@@ -19,6 +19,7 @@ for production deployments.
 |---|---|
 | **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 |
+| **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 |
 | **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 |
 | **Filters** — Input/output transformation and blocking via `Filter::Base` | Beta |
@@ -44,6 +45,7 @@ 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 |
 | **`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 |
 | **`stream` / `stream_async`** — Event callbacks execute on EventLoop and must return quickly | Beta |
@@ -66,7 +68,7 @@ for production deployments.
 | **`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 | Beta |
+| **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 |
 
 ## Public API boundary
@@ -76,12 +78,36 @@ Source declarations marked `@api private`, including most EventLoop/FSMSession a
 OffloadPool internals, are implementation details and may change without the same
 compatibility guarantees.
 
+The YARD `@api` classification is independent from Ruby language visibility in
+both directions. `@api public` marks a compatibility contract, but the Ruby
+visibility still follows the intended calling model: ordinary APIs may be
+public, subclass extension helpers may be protected, and constructors use
+Ruby-private `initialize` behind `.new`. `@api private` means "internal/no
+compatibility promise" and does not require a Ruby `private` declaration; some
+internal methods remain Ruby-public because Phronomy components call them
+through explicit receivers.
+
+Persistence Backend SPI methods are a deliberate exception to the ordinary
+application-facing interpretation of `@api public`: they are public extension
+contracts for backend implementers, but application business logic should usually
+interact with Agents/Workflows instead of calling low-level repository operations.
+See [Persistence backend contract](persistence-backends.md).
+
+`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:`.
+
 ## Advanced and internal APIs
 
 | Feature | Stability |
 |---|---|
 | **`Phronomy::Diagnostics`** — Snapshot of EventLoop lag/queue state and OffloadPool activity | Experimental |
 | **`Phronomy::Testing::FakeClock`** — Test-only deterministic clock helper | Beta |
+| **`Phronomy::Testing::PersistenceContract`** — Explicitly loaded RSpec conformance suite for custom Persistence backends | Beta |
+
+`Phronomy::Testing::PersistenceContract` is available only after explicit
+`require "phronomy/testing/persistence_contract"`. Ordinary
+`require "phronomy"` and production eager-load do not load RSpec.
 
 For runtime ownership and the distinction between public lifecycle APIs and
 private execution machinery, see [Runtime and concurrency](runtime-and-concurrency.md).

data/docs/getting-started.md

@@ -107,6 +107,13 @@ 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.
+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
+silently merged into the live instance.
+
 The active transcript and Knowledge views can be advanced independently without
 deleting the append-only canonical Journal:
 
@@ -172,6 +179,8 @@ end
 ```
 
 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.
 
 ## Workflow basics
 
@@ -188,7 +197,12 @@ end
 write_draft  = ->(state) { state.merge(draft: "Draft content") }
 review_draft = ->(state) { state.merge(feedback: "Feedback on: #{state.draft}") }
 
-workflow = Phronomy::Workflow.define(ReviewContext) do
+persistence = Phronomy::Persistence::InMemory.new
+
+workflow = Phronomy::Workflow.define(
+  ReviewContext,
+  persistence: persistence
+) do
   initial :write
   state :write, action: write_draft
   state :review, action: review_draft
@@ -207,6 +221,28 @@ final = workflow.send_event(state: state, event: :approve)
 puts final.approved
 ```
 
+`Persistence#workflow_states` is the durable Workflow repository. `thread_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
+save so another local invocation cannot start from a stale snapshot while the
+current owner is still committing.
+
+A global Persistence backend can be configured when Agents and Workflows should
+share one durable backend:
+
+```ruby
+Phronomy.configure do |config|
+  config.persistence = persistence
+end
+```
+
+Agent `new`/`create` and Workflow definitions use the global backend when they do
+not inject an explicit `persistence:`. Workflow durability is fixed at the
+application/Workflow-definition boundary; there is no per-invocation backend
+switch.
+
 Workflow entry and transition actions are synchronous Run-to-Completion
 callbacks. If a Workflow needs an Agent or another asynchronous lifecycle, start
 it asynchronously, return the Workflow context immediately, and deliver its

data/docs/migrations/0.19.md

@@ -0,0 +1,154 @@
+# Migrating to 0.19: Unified Persistence
+
+This release removes the separate Workflow `StateStore` abstraction and uses
+`Phronomy::Persistence` for both Agent and Workflow durable state.
+
+## Workflow persistence
+
+Before:
+
+```ruby
+store = Phronomy::StateStore::InMemory.new
+
+workflow = Phronomy::Workflow.define(
+  MyContext,
+  state_store: store
+) do
+  # ...
+end
+```
+
+After:
+
+```ruby
+persistence = Phronomy::Persistence::InMemory.new
+
+workflow = Phronomy::Workflow.define(
+  MyContext,
+  persistence: persistence
+) do
+  # ...
+end
+```
+
+Global configuration changes from:
+
+```ruby
+Phronomy.configure do |config|
+  config.state_store = store
+end
+```
+
+to:
+
+```ruby
+Phronomy.configure do |config|
+  config.persistence = persistence
+end
+```
+
+The global backend is also used by Agent `new`/`create` calls that do not pass an
+explicit `persistence:`. An explicitly injected Agent or Workflow backend still
+takes precedence over the global setting.
+
+Per-invocation `config[:state_store]` is removed. Persistence is selected at the
+Workflow definition/application boundary rather than switched on individual
+invocations.
+
+`Phronomy::StateStore`, `StateStore::InMemory`, and the `state_store:` Workflow
+parameter are removed without compatibility aliases.
+
+## workflow_states repository
+
+Custom Persistence backends must provide `workflow_states` with revision-aware
+load/save/delete semantics:
+
+```ruby
+record = persistence.workflow_states.load("order-123")
+
+persistence.workflow_states.save(
+  "order-123",
+  expected_revision: record&.fetch(:revision),
+  snapshot: {
+    fields: workflow_context.to_h,
+    phase: workflow_context.phase.to_s
+  }
+)
+```
+
+A stale revision must raise `Phronomy::Persistence::ConflictError` rather than
+silently overwriting newer durable state.
+
+Custom durable backends must also implement the public Backend SPI operation
+`Persistence#assert_agent_watermark!` used before next-LLM durable barriers. It
+verifies the caller's Agent revision and Journal position without returning
+replacement mutable state; mismatches raise `ConflictError`. SQL backends should
+implement this check inside the same database transaction as the subsequent
+durable write.
+
+The complete custom-backend contract is documented in
+[`docs/persistence-backends.md`](../persistence-backends.md). In particular,
+custom backends must provide the required capabilities, transaction atomicity,
+repository compare-and-swap semantics, and durable domain-object reconstruction
+described there.
+
+## Agent ownership and approval resume
+
+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:
+
+```ruby
+agent.approve(...)
+agent.approve_async(...)
+```
+
+The former class-level `MyAgent.approve(...)` / `MyAgent.approve_async(...)`
+routing APIs are removed. Applications that only have an `execution_id` should
+first resolve the current process's live owner:
+
+```ruby
+agent = MyAgent.live_for_execution(execution_id)
+
+agent.approve_async(
+  execution_id,
+  approval_request_id: request_id
+)
+```
+
+If the concrete Agent class is not known, use:
+
+```ruby
+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.
+
+`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
+request.
+
+## Workflow identity
+
+Do not treat the following as the same identifier:
+
+- `session_id`: application/tracing session metadata;
+- `thread_id`: durable Workflow state identity;
+- `fsm_session_id`: private Runtime identity for one FSMSession execution.
+
+The last value is internal and is regenerated for each invoke/resume. Applications
+continue to use `thread_id` when calling `Workflow#signal`.
+
+Workflow admission for a durable `thread_id` is Runtime/process-local. Separate
+Ruby processes or service replicas can execute the same `thread_id` concurrently
+unless the application adds distributed coordination. `workflow_states` optimistic
+revisions can reject a stale terminal commit, but they do not prevent duplicate
+execution from starting or undo external side effects already performed before a
+conflict is detected.