phronomy 0.19.0 → 0.20.0

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+RSpec.shared_examples "a workflow state repository" do
+  let(:repository) { persistence.workflow_states }
+
+  def workflow_contract_value(hash, key)
+    hash.key?(key) ? hash[key] : hash[key.to_s]
+  end
+
+  def workflow_contract_snapshot(record)
+    workflow_contract_value(record, :snapshot)
+  end
+
+  def workflow_contract_revision(record)
+    workflow_contract_value(record, :revision)
+  end
+
+  it "returns nil for an unknown thread_id" do
+    expect(repository.load("missing-#{SecureRandom.uuid}")).to be_nil
+  end
+
+  it "uses optimistic revisions for save" do
+    thread_id = "t1-#{SecureRandom.uuid}"
+    expect(
+      repository.save(
+        thread_id,
+        expected_revision: nil,
+        snapshot: {fields: {value: 1}, phase: "pause"}
+      )
+    ).to eq(1)
+
+    expect(
+      repository.save(
+        thread_id,
+        expected_revision: 1,
+        snapshot: {fields: {value: 2}, phase: "__end__"}
+      )
+    ).to eq(2)
+  end
+
+  it "rejects a stale expected_revision" do
+    thread_id = "t1-#{SecureRandom.uuid}"
+    repository.save(
+      thread_id,
+      expected_revision: nil,
+      snapshot: {fields: {value: 1}, phase: "pause"}
+    )
+
+    expect do
+      repository.save(
+        thread_id,
+        expected_revision: nil,
+        snapshot: {fields: {value: 2}, phase: "__end__"}
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "returns a snapshot representation accepted by WorkflowRunner" do
+    thread_id = "t1-#{SecureRandom.uuid}"
+    repository.save(
+      thread_id,
+      expected_revision: nil,
+      snapshot: {fields: {value: 1}, phase: "pause"}
+    )
+
+    record = repository.load(thread_id)
+    snapshot = workflow_contract_snapshot(record)
+    fields = workflow_contract_value(snapshot, :fields)
+
+    expect(workflow_contract_revision(record)).to eq(1)
+    expect(workflow_contract_value(fields, :value)).to eq(1)
+    expect(workflow_contract_value(snapshot, :phase)).to eq("pause")
+  end
+
+  it "isolates stored snapshots from caller mutation" do
+    thread_id = "t1-#{SecureRandom.uuid}"
+    repository.save(
+      thread_id,
+      expected_revision: nil,
+      snapshot: {fields: {values: [1]}, phase: "pause"}
+    )
+
+    loaded = repository.load(thread_id)
+    snapshot = workflow_contract_snapshot(loaded)
+    fields = workflow_contract_value(snapshot, :fields)
+    values = workflow_contract_value(fields, :values)
+
+    begin
+      values << 2
+    rescue FrozenError
+      nil
+    end
+
+    reloaded = repository.load(thread_id)
+    reloaded_fields = workflow_contract_value(
+      workflow_contract_snapshot(reloaded),
+      :fields
+    )
+    expect(workflow_contract_value(reloaded_fields, :values)).to eq([1])
+  end
+
+  it "deletes only at the expected revision" do
+    thread_id = "t1-#{SecureRandom.uuid}"
+    repository.save(
+      thread_id,
+      expected_revision: nil,
+      snapshot: {fields: {}, phase: "pause"}
+    )
+
+    expect do
+      repository.delete(thread_id, expected_revision: 99)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+
+    repository.delete(thread_id, expected_revision: 1)
+    expect(repository.load(thread_id)).to be_nil
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+RSpec.shared_examples "an Agent repository" do
+  let(:agent_repository) { persistence.agents }
+  let(:agent_root) do
+    Phronomy::Agent::AgentRoot.create(
+      agent_id: "contract-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+  end
+
+  it "creates and loads an AgentRoot" do
+    expect(agent_repository.create(agent_root).to_h).to eq(agent_root.to_h)
+    expect(agent_repository.load(agent_root.agent_id).to_h).to eq(agent_root.to_h)
+  end
+
+  it "rejects duplicate create" do
+    agent_repository.create(agent_root)
+
+    expect do
+      agent_repository.create(agent_root)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "raises NotFoundError for a missing Agent" do
+    expect do
+      agent_repository.load("missing-#{SecureRandom.uuid}")
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+
+  it "saves only at the expected revision" do
+    agent_repository.create(agent_root)
+    updated = agent_root.with(agent_revision: agent_root.agent_revision + 1)
+
+    expect(
+      agent_repository.save(
+        agent_root.agent_id,
+        expected_revision: agent_root.agent_revision,
+        root: updated
+      ).to_h
+    ).to eq(updated.to_h)
+
+    expect(agent_repository.load(agent_root.agent_id).agent_revision).to eq(1)
+  end
+
+  it "rejects a stale expected revision" do
+    agent_repository.create(agent_root)
+    first = agent_root.with(agent_revision: 1)
+    agent_repository.save(agent_root.agent_id, expected_revision: 0, root: first)
+    stale = agent_root.with(agent_revision: 1)
+
+    expect do
+      agent_repository.save(agent_root.agent_id, expected_revision: 0, root: stale)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rejects an Agent identity mismatch" do
+    agent_repository.create(agent_root)
+    other = Phronomy::Agent::AgentRoot.create(
+      agent_id: "other-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    ).with(agent_revision: 1)
+
+    expect do
+      agent_repository.save(
+        agent_root.agent_id,
+        expected_revision: 0,
+        root: other
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "requires revision to advance exactly once" do
+    agent_repository.create(agent_root)
+    skipped = agent_root.with(agent_revision: 2)
+
+    expect do
+      agent_repository.save(
+        agent_root.agent_id,
+        expected_revision: 0,
+        root: skipped
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "deletes idempotently" do
+    agent_repository.create(agent_root)
+    agent_repository.delete(agent_root.agent_id)
+    expect { agent_repository.delete(agent_root.agent_id) }.not_to raise_error
+
+    expect do
+      agent_repository.load(agent_root.agent_id)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+end

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.19.0"
+  VERSION = "0.20.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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-15 00:00:00.000000000 Z
+date: 2026-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -126,6 +126,7 @@ files:
 - docs/migrations/0.15.md
 - docs/migrations/0.16.md
 - docs/migrations/0.19.md
+- docs/persistence-backends.md
 - docs/runtime-and-concurrency.md
 - examples/workflows/agent_event_mapping.rb
 - examples/workflows/generic_task_event_mapping.rb
@@ -250,6 +251,13 @@ files:
 - lib/phronomy/testing/eval/scorer/includes_scorer.rb
 - lib/phronomy/testing/eval/scorer/llm_judge.rb
 - lib/phronomy/testing/fake_clock.rb
+- lib/phronomy/testing/persistence_contract.rb
+- lib/phronomy/testing/persistence_contract/a_content_store.rb
+- lib/phronomy/testing/persistence_contract/a_journal_repository.rb
+- lib/phronomy/testing/persistence_contract/a_persistence_backend.rb
+- lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
+- lib/phronomy/testing/persistence_contract/an_agent_repository.rb
+- lib/phronomy/testing/persistence_contract/an_execution_repository.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tools/agent.rb
 - lib/phronomy/tools/mcp.rb
@@ -283,7 +291,6 @@ files:
 - scripts/add_to_h_unnamed_doubles.rb
 - scripts/api_snapshot.rb
 - scripts/check_api_annotations.rb
-- scripts/check_private_enforcement.rb
 - scripts/check_readme_ruby.rb
 - scripts/check_readme_runnable.rb
 - scripts/migrate_spec_agent_definition.rb

data/scripts/check_private_enforcement.rb

@@ -1,93 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# check_private_enforcement.rb
-#
-# Verifies that every instance method annotated @api private in lib/ is
-# actually non-public at the Ruby level (i.e., NOT in Module#public_instance_methods).
-#
-# Class methods (def self.xxx) are excluded from this check because their
-# visibility is managed separately on the singleton class and rarely causes
-# accidental public exposure to consumers.
-#
-# Usage (run from the phronomy/ repository root):
-#   bundle exec ruby scripts/check_private_enforcement.rb
-#
-# Exit codes:
-#   0 — all @api private instance methods are non-public (or have no Ruby def)
-#   1 — one or more @api private instance methods are exposed as public
-
-require "bundler/setup"
-require_relative "../lib/phronomy"
-
-lib_dir = File.expand_path("../lib", __dir__)
-
-unless File.directory?(lib_dir)
-  warn "ERROR: lib directory not found at #{lib_dir}"
-  exit 1
-end
-
-# Step 1: Collect instance methods annotated @api private via static analysis.
-api_private_entries = []
-
-Dir.glob(File.join(lib_dir, "**", "*.rb")).sort.each do |file|
-  lines = File.readlines(file)
-
-  lines.each_with_index do |line, i|
-    next unless line.match?(/^\s*#\s*@api\s+private\s*$/)
-
-    # Advance past any further comment or blank lines to reach the def.
-    j = i + 1
-    j += 1 while j < lines.size && lines[j].match?(/^\s*(#|$)/)
-    next unless j < lines.size
-
-    # Skip class-level methods — they live on the singleton class, not as
-    # public instance methods accessible to consumers.
-    next if lines[j].match?(/def\s+self\./)
-
-    # Match both plain def and "private def".
-    m = lines[j].match(/^\s*(?:private\s+)?def\s+(\w+[!?=]?)/)
-    next unless m
-
-    rel_path = file.sub("#{lib_dir}/../", "")
-    api_private_entries << {name: m[1].to_sym, file: rel_path, line: j + 1}
-  end
-end
-
-if api_private_entries.empty?
-  puts "No @api private instance methods found."
-  exit 0
-end
-
-# Step 2: Build a map of publicly exposed instance methods across all
-# Phronomy-namespaced modules/classes (own methods only, no inheritance).
-all_phronomy_modules = ObjectSpace.each_object(Module).select do |mod|
-  mod.name&.start_with?("Phronomy")
-end
-
-public_exposure_map = {}
-all_phronomy_modules.each do |mod|
-  mod.public_instance_methods(false).each do |meth|
-    (public_exposure_map[meth] ||= []) << mod.name
-  end
-end
-
-# Step 3: Report violations — @api private methods that are still public.
-errors = []
-
-api_private_entries.each do |entry|
-  exposing_modules = public_exposure_map[entry[:name]]
-  next unless exposing_modules
-
-  errors << "#{entry[:file]}:#{entry[:line]}  def #{entry[:name]}" \
-            "  (annotated @api private but public in: #{exposing_modules.join(", ")})"
-end
-
-if errors.empty?
-  puts "OK: all #{api_private_entries.size} @api private instance methods are non-public."
-  exit 0
-else
-  warn "ERROR: #{errors.size} @api private instance method(s) are exposed as public:"
-  errors.each { |e| warn "  #{e}" }
-  exit 1
-end