phronomy 0.19.0 → 0.21.0

data/lib/phronomy/testing/persistence_contract/an_execution_repository.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+RSpec.shared_examples "an Execution repository" do
+  let(:execution_repository) { persistence.executions }
+  let(:execution_agent_root) do
+    Phronomy::Agent::AgentRoot.create(
+      agent_id: "execution-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+  end
+
+  def build_contract_execution(root)
+    input_record = Phronomy::Agent::JournalRecord.new(
+      agent_id: root.agent_id,
+      kind: :input_received,
+      channel: :external,
+      role: :user,
+      context_candidate: false
+    )
+    Phronomy::Agent::AgentExecution.start(
+      agent_root: root,
+      input_record: input_record
+    )
+  end
+
+  before do
+    persistence.agents.create(execution_agent_root)
+  end
+
+  it "creates and loads an active execution" do
+    execution = build_contract_execution(execution_agent_root)
+
+    expect(execution_repository.create_active(execution).to_h).to eq(execution.to_h)
+    expect(execution_repository.load(execution.execution_id).to_h).to eq(execution.to_h)
+  end
+
+  it "raises NotFoundError for a missing execution" do
+    expect do
+      execution_repository.load("missing-#{SecureRandom.uuid}")
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+
+  it "rejects a duplicate execution_id" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+
+    expect do
+      execution_repository.create_active(execution)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "admits at most one active or suspended execution for one Agent" do
+    first = build_contract_execution(execution_agent_root)
+    second = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(first)
+
+    expect do
+      execution_repository.create_active(second)
+    end.to raise_error(Phronomy::AgentBusyError)
+  end
+
+  it "allows different Agents to have active executions" do
+    other_root = Phronomy::Agent::AgentRoot.create(
+      agent_id: "execution-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+    persistence.agents.create(other_root)
+
+    expect do
+      execution_repository.create_active(build_contract_execution(execution_agent_root))
+      execution_repository.create_active(build_contract_execution(other_root))
+    end.not_to raise_error
+  end
+
+  it "saves only at the expected execution revision" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    updated = execution.with(status: :active, phase: :calling_llm)
+
+    expect(
+      execution_repository.save(
+        execution.execution_id,
+        expected_revision: 0,
+        execution: updated
+      ).to_h
+    ).to eq(updated.to_h)
+    expect(execution_repository.load(execution.execution_id).execution_revision).to eq(1)
+  end
+
+  it "rejects a stale execution revision" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    updated = execution.with(status: :active, phase: :calling_llm)
+    execution_repository.save(
+      execution.execution_id,
+      expected_revision: 0,
+      execution: updated
+    )
+
+    expect do
+      execution_repository.save(
+        execution.execution_id,
+        expected_revision: 0,
+        execution: updated
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rejects an execution identity mismatch" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    other_root = Phronomy::Agent::AgentRoot.create(
+      agent_id: "execution-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+    persistence.agents.create(other_root)
+    other = build_contract_execution(other_root).with(
+      execution_revision: 1,
+      status: :active,
+      phase: :calling_llm
+    )
+
+    expect do
+      execution_repository.save(
+        execution.execution_id,
+        expected_revision: 0,
+        execution: other
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "requires execution revision to advance exactly once" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    skipped = execution.with(
+      execution_revision: 2,
+      status: :active,
+      phase: :calling_llm
+    )
+
+    expect do
+      execution_repository.save(
+        execution.execution_id,
+        expected_revision: 0,
+        execution: skipped
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "lists active executions for one Agent" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+
+    expect(execution_repository.list_active(execution_agent_root.agent_id).map(&:execution_id))
+      .to eq([execution.execution_id])
+  end
+
+  it "asserts idle state and rejects active Agents" do
+    expect do
+      execution_repository.assert_idle!(execution_agent_root.agent_id)
+    end.not_to raise_error
+
+    execution_repository.create_active(build_contract_execution(execution_agent_root))
+
+    expect do
+      execution_repository.assert_idle!(execution_agent_root.agent_id)
+    end.to raise_error(Phronomy::AgentBusyError)
+  end
+
+  it "deletes one execution" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    execution_repository.delete(execution.execution_id)
+
+    expect do
+      execution_repository.load(execution.execution_id)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+
+  it "deletes all executions for one Agent without deleting other Agents' executions" do
+    other_root = Phronomy::Agent::AgentRoot.create(
+      agent_id: "execution-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+    persistence.agents.create(other_root)
+    own = build_contract_execution(execution_agent_root)
+    other = build_contract_execution(other_root)
+    execution_repository.create_active(own)
+    execution_repository.create_active(other)
+
+    execution_repository.delete_for_agent(execution_agent_root.agent_id)
+
+    expect(execution_repository.list_active(execution_agent_root.agent_id)).to be_empty
+    expect(execution_repository.load(other.execution_id).execution_id).to eq(other.execution_id)
+  end
+end

data/lib/phronomy/testing/persistence_contract.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "phronomy"
+
+begin
+  require "rspec/core"
+  require "rspec/expectations"
+rescue LoadError => error
+  raise LoadError,
+    "Phronomy Persistence contract support requires RSpec. " \
+    "Add `rspec` to the backend project's development/test dependencies before " \
+    "requiring `phronomy/testing/persistence_contract`.",
+    error.backtrace
+end
+
+module Phronomy
+  module Testing
+    # Explicitly loaded RSpec shared examples for Persistence backend authors.
+    #
+    # This namespace is intentionally excluded from Phronomy's production
+    # Zeitwerk eager-load path. Requiring this file is the opt-in boundary that
+    # loads RSpec and the backend conformance suite.
+    module PersistenceContract
+      SHARED_EXAMPLES = [
+        "a persistence content store",
+        "an Agent repository",
+        "a Journal repository",
+        "an Execution repository",
+        "a workflow state repository",
+        "a Persistence backend"
+      ].freeze
+    end
+  end
+end
+
+require_relative "persistence_contract/a_content_store"
+require_relative "persistence_contract/an_agent_repository"
+require_relative "persistence_contract/a_journal_repository"
+require_relative "persistence_contract/an_execution_repository"
+require_relative "persistence_contract/a_workflow_state_repository"
+require_relative "persistence_contract/a_persistence_backend"

data/lib/phronomy/tool/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tool
+    # Public authoring façade for Phronomy Tools.
+    #
+    # This constant intentionally refers to the exact same Class object as
+    # {Phronomy::Agent::Context::Capability::Base}. The implementation namespace
+    # remains canonical internally so the existing Tool DSL state, inheritance,
+    # built-in Tools, and compatibility surface are not duplicated.
+    #
+    # @api public
+    Base = Phronomy::Agent::Context::Capability::Base
+  end
+end

data/lib/phronomy/tool.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Public authoring namespace for application-defined Tools.
+  #
+  # Concrete Tools supplied by Phronomy remain under {Phronomy::Tools}.
+  #
+  # @api public
+  module Tool
+  end
+end

data/lib/phronomy/vector_store/async_backend.rb

@@ -2,43 +2,29 @@
 
 module Phronomy
   module VectorStore
-    # Mixin that defines the async interface for VectorStore backends.
+    # Framework-owned async convenience methods for VectorStore backends.
     #
-    # Mixing this module into a VectorStore class provides three choices:
+    # The backend extension contract is the synchronous interface defined by
+    # {VectorStore::Base}: add/search/remove/clear/size. These async convenience
+    # methods are inherited by backends and route that synchronous work through
+    # Phronomy's bounded {OffloadPool}. This keeps OS-thread creation, queue
+    # backpressure, submit timeout/cancellation, and completion semantics owned by
+    # the framework rather than by each backend.
     #
-    # 1. **Do nothing** — inherits default implementations from {VectorStore::Base}
-    #    that route through {OffloadPool}.
+    # A future genuine native-async backend may adapt its completion into a
+    # {Phronomy::Task} without an OffloadPool worker, but native async override is
+    # not part of the current backend SPI.
     #
-    # 2. **Override selectively** — override only the async methods where the
-    #    backend has a native async driver, while the remaining methods fall back
-    #    to the pool.
-    #
-    # 3. **Implement all natively** — override all async methods to avoid pool
-    #    allocation entirely.
-    #
-    # @example Native async search (no pool worker thread allocated)
-    #   class MyFastStore < Phronomy::VectorStore::Base
-    #     include Phronomy::VectorStore::AsyncBackend
-    #
-    #     def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
-    #       # Returns a PendingOperation backed by a native async driver.
-    #       native_async_search(query_embedding, k)
-    #     end
-    #   end
-    #
-    # @api public
+    # @api private
     module AsyncBackend
       # Async variant of {VectorStore::Base#add}.
       #
-      # Submits the add call to {OffloadPool} by default.
-      # Override to use a native async driver.
-      #
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task]
       # @api public
       def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -52,14 +38,11 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#search}.
       #
-      # Submits the search call to {OffloadPool} by default.
-      # Override to use a native async driver.
-      #
       # @param query_embedding    [Array<Float>]
       # @param k                  [Integer]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task]
       # @api public
       def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -73,13 +56,10 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#remove}.
       #
-      # Submits the remove call to {OffloadPool} by default.
-      # Override to use a native async driver.
-      #
       # @param id                 [String]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task]
       # @api public
       def remove_async(id:, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -93,12 +73,9 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#clear}.
       #
-      # Submits the clear call to {OffloadPool} by default.
-      # Override to use a native async driver.
-      #
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task]
       # @api public
       def clear_async(cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/vector_store/base.rb

@@ -2,24 +2,22 @@
 
 module Phronomy
   module VectorStore
-    # Abstract interface for vector stores.
+    # Public extension SPI for vector stores.
     #
-    # Implementations manage a collection of (embedding, metadata) pairs and
-    # support similarity search.
+    # Backends implement the synchronous add/search/remove/clear/size contract.
+    # Phronomy supplies async convenience methods through {AsyncBackend}; blocking
+    # backend work is offloaded through the framework-owned bounded OffloadPool.
     #
-    # Async methods (`search_async`, `add_async`, `remove_async`, `clear_async`)
-    # are provided by the {AsyncBackend} mixin which defaults to routing calls
-    # through {OffloadPool}. Backends with native async drivers may override
-    # individual async methods without touching the pool at all.
+    # @api public
     class Base
       include AsyncBackend
 
       # Add a document with its vector embedding.
       #
-      # @param id                 [String]                         unique document identifier
-      # @param embedding          [Array<Float>]                   vector embedding
-      # @param metadata           [Hash]                           arbitrary metadata (e.g. the original message object)
-      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @param id                 [String] unique document identifier
+      # @param embedding          [Array<Float>] vector embedding
+      # @param metadata           [Hash] arbitrary metadata
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @api public
       def add(id:, embedding:, metadata: {}, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
@@ -29,8 +27,8 @@ module Phronomy
       # Return the k most similar documents to the query embedding.
       #
       # @param query_embedding    [Array<Float>]
-      # @param k                  [Integer]                        number of results
-      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @param k                  [Integer] number of results
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @return [Array<Hash>] each element: { id:, score:, metadata: }
       # @api public
       def search(query_embedding:, k: 5, cancellation_token: nil)
@@ -47,6 +45,7 @@ module Phronomy
       end
 
       # Remove all documents.
+      # @api public
       def clear
         raise NotImplementedError, "#{self.class}#clear is not implemented"
       end

data/lib/phronomy/vector_store/embeddings/base.rb

@@ -3,15 +3,18 @@
 module Phronomy
   module VectorStore
     module Embeddings
-      # Abstract interface for embedding adapters.
+      # Public extension SPI for embedding adapters.
       #
-      # Concrete implementations must override {#embed} and return a vector
-      # as an +Array<Float>+.
+      # Concrete implementations override {#embed}. Phronomy owns the async
+      # bridge: {#embed_async} routes the synchronous implementation through the
+      # bounded OffloadPool and returns a {Phronomy::Task}.
+      #
+      # @api public
       class Base
         # Embed the given text and return a vector representation.
         #
-        # @param text               [String]                         the text to embed
-        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+        # @param text               [String] the text to embed
+        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
         # @return [Array<Float>] the embedding vector
         # @api public
         def embed(text, cancellation_token = nil)
@@ -19,13 +22,12 @@ module Phronomy
           raise NotImplementedError, "#{self.class}#embed is not implemented"
         end
 
-        # Submits an {#embed} call to {OffloadPool} and returns an
-        # {OffloadPool::PendingOperation}.
+        # Submits an {#embed} call to {OffloadPool}.
         #
         # @param text               [String]
         # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-        # @param timeout            [Numeric, nil] seconds before the operation is abandoned
-        # @return [OffloadPool::PendingOperation]
+        # @param timeout            [Numeric, nil] operation-wide submit timeout
+        # @return [Phronomy::Task]
         # @api public
         def embed_async(text, cancellation_token = nil, timeout: nil)
           Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.19.0"
+  VERSION = "0.21.0"
 end

data/lib/phronomy.rb

@@ -21,6 +21,12 @@ loader.inflector.inflect("before_llm_input" => "BeforeLLMInput")
 loader.collapse("#{__dir__}/phronomy/engine")
 # Loaded via require_relative before loader.setup; ignore to avoid Zeitwerk constant-name mismatch.
 loader.ignore("#{__dir__}/phronomy/ruby_llm_patches.rb")
+# Persistence backend conformance tests are explicit test support. Keep them out
+# of production eager-load so ordinary `require "phronomy"` never requires RSpec.
+loader.ignore(
+  "#{__dir__}/phronomy/testing/persistence_contract.rb",
+  "#{__dir__}/phronomy/testing/persistence_contract"
+)
 loader.setup
 
 require_relative "phronomy/version"

data/scripts/run_mutation.sh

@@ -13,7 +13,8 @@
 # Target: mutation score >= 80% for each listed subject.
 # Baseline scores (as of initial run):
 #   Phronomy::WorkflowContext  84.85%
-#   Phronomy::Tool::Base       55.74%
+#   Phronomy::Agent::Context::Capability::Base  55.74%
+#     (public facade alias: Phronomy::Tool::Base; same Class object)
 #
 # Note: mutation testing is slow (~1-5 min per subject). Run locally or via
 # the nightly-mutation GitHub Actions workflow.

data/sig/phronomy/agent.rbs

@@ -0,0 +1,36 @@
+module Phronomy
+  module Agent
+    class Base
+      def self.model: (?String name) -> String?
+      def self.instructions: (?untyped text) { (untyped) -> untyped } -> untyped
+                           | (?untyped text) -> untyped
+      def self.tools: (?Hash[Class, String?] definitions) -> untyped
+      def self.tool_aliases: () -> Hash[Class, String]
+      def self.provider: (?Symbol name) -> Symbol?
+      def self.temperature: (?Float value) -> Float?
+      def self.max_iterations: (?Integer value) -> Integer
+      def self.cache_instructions: (?bool enabled) -> bool?
+      def self.max_output_tokens: (?Integer value) -> Integer?
+      def self.context_window: (?Integer value) -> Integer?
+      def self.agent_definition: (?id: String?, ?version: Integer?) -> Hash[Symbol, untyped]
+      def self.create: (?agent_id: String, ?context: untyped, ?knowledge: Array[untyped], ?persistence: Persistence?, ?metadata: Hash[untyped, untyped]) -> instance
+      def self.load: (String agent_id, persistence: Persistence) -> instance
+      def self.live_for_execution: (String execution_id) -> instance
+
+      attr_reader agent_id: String
+      attr_reader persistence: Persistence
+
+      def invoke: (untyped input, **untyped) -> Hash[Symbol, untyped]
+      def invoke_async: (untyped input, **untyped) -> Task[Hash[Symbol, untyped]]
+      def stream: (untyped input, **untyped) { (untyped event) -> void } -> Hash[Symbol, untyped]
+      def stream_async: (untyped input, **untyped) -> Task[Hash[Symbol, untyped]]
+      def transcript: () -> Array[untyped]
+      def add_knowledge: (untyped content, ?metadata: Hash[untyped, untyped]) -> self
+      def clear_transcript!: () -> untyped
+      def clear_knowledge!: () -> untyped
+      def reset_context!: () -> untyped
+      def close!: () -> untyped
+      def purge!: () -> bool
+    end
+  end
+end

data/sig/phronomy/extensions.rbs

@@ -0,0 +1,50 @@
+module Phronomy
+  module Filter
+    class Base
+      def call: (untyped value, **untyped context) -> untyped
+    end
+  end
+
+  module OutputParser
+    class Base
+      def parse: (String text) -> untyped
+      def invoke: (untyped input, ?config: Hash[untyped, untyped]) -> untyped
+    end
+  end
+
+  module Tracing
+    class Base
+      def start_span: (String name, **untyped attributes) -> untyped
+      def finish_span: (untyped span, ?output: untyped, ?usage: untyped, ?error: Exception?) -> untyped
+      def trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, untyped] } -> A
+    end
+  end
+
+  module VectorStore
+    class Base
+      def add: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?) -> untyped
+      def search: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?) -> Array[Hash[Symbol, untyped]]
+      def remove: (id: String) -> untyped
+      def clear: () -> untyped
+      def size: () -> Integer
+
+      def add_async: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
+      def search_async: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[Array[Hash[Symbol, untyped]]]
+      def remove_async: (id: String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
+      def clear_async: (?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
+    end
+
+    module Embeddings
+      class Base
+        def embed: (String text, ?Concurrency::CancellationToken? cancellation_token) -> Array[Float]
+        def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> Task[Array[Float]]
+      end
+    end
+  end
+  module Testing
+    module PersistenceContract
+      SHARED_EXAMPLES: Array[String]
+    end
+  end
+
+end

data/sig/phronomy/llm_adapter.rbs

@@ -0,0 +1,11 @@
+module Phronomy
+  module LLMAdapter
+    class Base
+      def complete: (untyped chat, String? message, ?config: Hash[untyped, untyped]) -> untyped
+      def stream: (untyped chat, String? message, ?config: Hash[untyped, untyped]) { (untyped chunk) -> void } -> untyped
+    end
+
+    class RubyLLM < Base
+    end
+  end
+end

data/sig/phronomy/persistence.rbs

@@ -0,0 +1,70 @@
+module Phronomy
+  interface _ContentRepository
+    def put: (String bytes, canonicalization_version: untyped) -> String
+    def fetch: (String content_id) -> String
+    def exist?: (String content_id) -> bool
+  end
+
+  interface _AgentRepository
+    def create: (untyped root) -> untyped
+    def load: (String agent_id) -> untyped
+    def save: (String agent_id, expected_revision: Integer, root: untyped) -> untyped
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _JournalRepository
+    def append: (String agent_id, expected_position: Integer, records: Array[untyped]) -> Array[untyped]
+    def read: (String agent_id, ?after: Integer?, ?limit: Integer?) -> Array[untyped]
+    def head: (String agent_id) -> Integer
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _ExecutionRepository
+    def create_active: (untyped execution) -> untyped
+    def load: (String execution_id) -> untyped
+    def save: (String execution_id, expected_revision: Integer, execution: untyped) -> untyped
+    def list_active: (String agent_id) -> Array[untyped]
+    def delete: (String execution_id) -> untyped
+    def delete_for_agent: (String agent_id) -> untyped
+    def assert_idle!: (String agent_id) -> untyped
+  end
+
+  interface _WorkflowStateRepository
+    def load: (String thread_id) -> Hash[untyped, untyped]?
+    def save: (String thread_id, expected_revision: Integer?, snapshot: Hash[untyped, untyped]) -> untyped
+    def delete: (String thread_id, expected_revision: Integer) -> untyped
+  end
+
+  interface _PersistenceTransactionView
+    def contents: () -> _ContentRepository
+    def agents: () -> _AgentRepository
+    def journals: () -> _JournalRepository
+    def executions: () -> _ExecutionRepository
+    def workflow_states: () -> _WorkflowStateRepository
+    def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
+  end
+
+  class Persistence
+    class ConflictError < Phronomy::Error
+    end
+    class NotFoundError < Phronomy::Error
+    end
+    class UnsupportedBackendError < Phronomy::Error
+    end
+    class SerializationError < Phronomy::Error
+    end
+
+    REQUIRED_CAPABILITIES: Hash[Symbol, bool]
+
+    attr_reader contents: _ContentRepository
+    attr_reader agents: _AgentRepository
+    attr_reader journals: _JournalRepository
+    attr_reader executions: _ExecutionRepository
+    attr_reader workflow_states: _WorkflowStateRepository
+
+    def initialize: (contents: _ContentRepository, agents: _AgentRepository, journals: _JournalRepository, executions: _ExecutionRepository, workflow_states: _WorkflowStateRepository) -> void
+    def capabilities: () -> Hash[Symbol, bool]
+    def transaction: () { (_PersistenceTransactionView) -> untyped } -> untyped
+    def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
+  end
+end