phronomy 0.19.0 → 0.20.0

data/lib/phronomy/agent/llm_call_record.rb

@@ -39,6 +39,10 @@ module Phronomy
         freeze
       end
 
+      # Returns the canonical durable representation of this LLM Call record.
+      #
+      # @return [Hash{String => Object}]
+      # @api public
       def to_h
         ATTRIBUTES.to_h do |name|
           value = public_send(name)
@@ -46,6 +50,22 @@ module Phronomy
           [name.to_s, value]
         end
       end
+
+      # Restores an LLM Call record from its canonical durable representation.
+      # String and Symbol top-level keys are accepted so database adapters may
+      # pass either a parsed JSON object or a Ruby-native Hash.
+      #
+      # @param hash [Hash]
+      # @return [LLMCallRecord]
+      # @api public
+      def self.from_h(hash)
+        attributes = ATTRIBUTES.to_h do |name|
+          key = hash.key?(name.to_s) ? name.to_s : name
+          [name, hash.fetch(key)]
+        end
+        attributes[:status] = attributes.fetch(:status).to_sym
+        new(**attributes)
+      end
     end
   end
 end

data/lib/phronomy/persistence.rb

@@ -5,9 +5,53 @@ module Phronomy
     class ConflictError < Phronomy::Error; end
     class NotFoundError < Phronomy::Error; end
     class UnsupportedBackendError < Phronomy::Error; end
+    class SerializationError < Phronomy::Error; end
 
-    attr_reader :contents, :agents, :journals, :executions, :workflow_states
+    REQUIRED_CAPABILITIES = {
+      atomic_all: true,
+      atomic_admission: true,
+      optimistic_revision: true
+    }.freeze
 
+    # Durable repository accessors supplied by a Persistence backend.
+    #
+    # The repository objects are part of the Backend SPI. They may be private
+    # implementation classes owned by the backend; they do not need to inherit
+    # from Phronomy repository base classes.
+    #
+    # @return [Object] content-addressed immutable content repository
+    # @api public
+    attr_reader :contents
+
+    # @return [Object] AgentRoot repository
+    # @api public
+    attr_reader :agents
+
+    # @return [Object] append-only Agent Journal repository
+    # @api public
+    attr_reader :journals
+
+    # @return [Object] AgentExecution repository
+    # @api public
+    attr_reader :executions
+
+    # @return [Object] durable Workflow snapshot repository
+    # @api public
+    attr_reader :workflow_states
+
+    # Initializes a Persistence backend with its durable repositories.
+    #
+    # Subclasses normally construct backend-specific repository objects and then
+    # call +super+. The backend must advertise every capability in
+    # {REQUIRED_CAPABILITIES}; construction fails fast otherwise.
+    #
+    # @param contents [Object]
+    # @param agents [Object]
+    # @param journals [Object]
+    # @param executions [Object]
+    # @param workflow_states [Object]
+    # @raise [UnsupportedBackendError] when a required capability is missing
+    # @api public
     def initialize(contents:, agents:, journals:, executions:, workflow_states:)
       @contents = contents
       @agents = agents
@@ -17,18 +61,67 @@ module Phronomy
       validate_capabilities!
     end
 
+    # Declares storage semantics provided by this backend.
+    #
+    # Required meanings:
+    # - +atomic_all+: all durable repositories can participate in one atomic
+    #   transaction domain.
+    # - +atomic_admission+: Agent execution admission is atomic; at most one
+    #   active/suspended execution may be admitted for one Agent. This does not
+    #   mean cross-process Workflow admission or distributed locking.
+    # - +optimistic_revision+: Agent, Execution, Workflow revision checks and
+    #   Journal position checks provide compare-and-swap conflict detection.
+    #
+    # @return [Hash{Symbol => Boolean}]
+    # @api public
     def capabilities
-      {atomic_all: false, atomic_admission: false}.freeze
+      {
+        atomic_all: false,
+        atomic_admission: false,
+        optimistic_revision: false
+      }.freeze
     end
 
+    # Executes one atomic durable transaction.
+    #
+    # The object yielded to the block is a transaction-scoped Persistence view.
+    # It must respond to +contents+, +agents+, +journals+, +executions+,
+    # +workflow_states+, and +assert_agent_watermark!+. It may be +self+, but
+    # backends are free to yield a separate transaction view backed by a checked
+    # out connection/session.
+    #
+    # If the block raises, mutations made through the transaction view must not
+    # be committed. Storage failures whose commit outcome is fundamentally
+    # unknown remain backend/database failures; Phronomy does not claim
+    # exactly-once semantics for such failures.
+    #
+    # @yieldparam transaction_view [Object]
+    # @return [Object] the block result
+    # @raise [UnsupportedBackendError] when atomic transactions are unavailable
+    # @api public
     def transaction
       raise UnsupportedBackendError, "#{self.class} does not provide atomic_all"
     end
 
     # Verifies that a live Agent still owns the durable base it hydrated.
-    # Backends should implement this as a revision/position precondition check,
-    # not as a state reload returned to the caller.
-    # @api private
+    #
+    # This is a Backend SPI operation invoked by Phronomy at durable barriers.
+    # Ordinary application code should not call it directly. The backend must
+    # compare the stored Agent revision and current Journal position against the
+    # supplied watermark in the same storage consistency view used by subsequent
+    # writes in the surrounding transaction.
+    #
+    # The method is a precondition check only. It must not reload or return
+    # replacement mutable Agent state; the live Agent remains the logical owner.
+    #
+    # @param agent_id [String]
+    # @param agent_revision [Integer]
+    # @param journal_position [Integer]
+    # @return [true]
+    # @raise [NotFoundError] when the Agent does not exist
+    # @raise [ConflictError] when either durable watermark component differs
+    # @raise [UnsupportedBackendError] when the backend does not implement the check
+    # @api public
     def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
       raise UnsupportedBackendError,
         "#{self.class} does not provide Agent durable-watermark checks"
@@ -37,8 +130,9 @@ module Phronomy
     private
 
     def validate_capabilities!
-      required = {atomic_all: true, atomic_admission: true}
-      missing = required.reject { |key, value| capabilities[key] == value }
+      missing = REQUIRED_CAPABILITIES.reject do |key, value|
+        capabilities[key] == value
+      end
       return if missing.empty?
 
       raise UnsupportedBackendError,

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "a persistence content store" do
+  let(:content_store) { persistence.contents }
+
+  it "returns the same content_id for the same bytes" do
+    first = content_store.put("same".b, canonicalization_version: 1)
+    second = content_store.put("same".b, canonicalization_version: 1)
+
+    expect(second).to eq(first)
+  end
+
+  it "round-trips binary bytes" do
+    bytes = "\x00\xFFpayload".b
+    content_id = content_store.put(bytes, canonicalization_version: 1)
+
+    expect(content_store.fetch(content_id)).to eq(bytes)
+    expect(content_store.exist?(content_id)).to be(true)
+  end
+
+  it "raises NotFoundError for a missing content_id" do
+    expect do
+      content_store.fetch("sha256:#{"0" * 64}")
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+
+  it "isolates durable bytes from mutation of fetched values" do
+    content_id = content_store.put("immutable".b, canonicalization_version: 1)
+    fetched = content_store.fetch(content_id)
+    fetched << "-caller-change"
+
+    expect(content_store.fetch(content_id)).to eq("immutable".b)
+  end
+
+  it "supports UTF-8 text helpers" do
+    content_id = content_store.put_text("Grüße")
+
+    expect(content_store.fetch_text(content_id)).to eq("Grüße")
+  end
+
+  it "supports canonical JSON helpers" do
+    value = {
+      "z" => [1, true, nil],
+      "a" => {"message" => "hello"}
+    }
+    content_id = content_store.put_json(value)
+
+    expect(content_store.fetch_json(content_id)).to eq(value)
+  end
+end

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+RSpec.shared_examples "a Journal repository" do
+  let(:journal_repository) { persistence.journals }
+  let(:journal_agent_root) do
+    Phronomy::Agent::AgentRoot.create(
+      agent_id: "journal-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+  end
+
+  def build_contract_journal_record(agent_id:, record_id: SecureRandom.uuid, content_ref: nil)
+    Phronomy::Agent::JournalRecord.new(
+      agent_id: agent_id,
+      record_id: record_id,
+      kind: :knowledge,
+      channel: :context,
+      role: :user,
+      content_ref: content_ref,
+      context_candidate: true
+    )
+  end
+
+  before do
+    persistence.agents.create(journal_agent_root)
+  end
+
+  it "appends records at the expected position and assigns durable sequences" do
+    first = build_contract_journal_record(agent_id: journal_agent_root.agent_id)
+    second = build_contract_journal_record(agent_id: journal_agent_root.agent_id)
+
+    appended = journal_repository.append(
+      journal_agent_root.agent_id,
+      expected_position: 0,
+      records: [first, second]
+    )
+
+    expect(appended.map(&:sequence)).to eq([1, 2])
+    expect(journal_repository.head(journal_agent_root.agent_id)).to eq(2)
+  end
+
+  it "rejects an unexpected append position" do
+    record = build_contract_journal_record(agent_id: journal_agent_root.agent_id)
+
+    expect do
+      journal_repository.append(
+        journal_agent_root.agent_id,
+        expected_position: 1,
+        records: [record]
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rejects a duplicate record_id already present in the Journal" do
+    record_id = SecureRandom.uuid
+    first = build_contract_journal_record(
+      agent_id: journal_agent_root.agent_id,
+      record_id: record_id
+    )
+    duplicate = build_contract_journal_record(
+      agent_id: journal_agent_root.agent_id,
+      record_id: record_id
+    )
+    journal_repository.append(
+      journal_agent_root.agent_id,
+      expected_position: 0,
+      records: [first]
+    )
+
+    expect do
+      journal_repository.append(
+        journal_agent_root.agent_id,
+        expected_position: 1,
+        records: [duplicate]
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rejects duplicate record_ids within one append" do
+    record_id = SecureRandom.uuid
+    records = 2.times.map do
+      build_contract_journal_record(
+        agent_id: journal_agent_root.agent_id,
+        record_id: record_id
+      )
+    end
+
+    expect do
+      journal_repository.append(
+        journal_agent_root.agent_id,
+        expected_position: 0,
+        records: records
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rejects records belonging to another Agent" do
+    record = build_contract_journal_record(agent_id: "other-agent")
+
+    expect do
+      journal_repository.append(
+        journal_agent_root.agent_id,
+        expected_position: 0,
+        records: [record]
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "reads records in sequence order and supports after/limit" do
+    records = 3.times.map do
+      build_contract_journal_record(agent_id: journal_agent_root.agent_id)
+    end
+    appended = journal_repository.append(
+      journal_agent_root.agent_id,
+      expected_position: 0,
+      records: records
+    )
+
+    expect(journal_repository.read(journal_agent_root.agent_id).map(&:record_id))
+      .to eq(appended.map(&:record_id))
+    expect(journal_repository.read(journal_agent_root.agent_id, after: 1).map(&:sequence))
+      .to eq([2, 3])
+    expect(journal_repository.read(journal_agent_root.agent_id, limit: 2).map(&:sequence))
+      .to eq([1, 2])
+  end
+
+  it "isolates durable Journal state from mutation of returned collections" do
+    record = build_contract_journal_record(agent_id: journal_agent_root.agent_id)
+    journal_repository.append(
+      journal_agent_root.agent_id,
+      expected_position: 0,
+      records: [record]
+    )
+    loaded = journal_repository.read(journal_agent_root.agent_id)
+
+    begin
+      loaded.clear
+    rescue FrozenError
+      nil
+    end
+
+    expect(journal_repository.read(journal_agent_root.agent_id).length).to eq(1)
+  end
+
+  it "returns an empty Journal with head zero when no records exist" do
+    expect(journal_repository.read(journal_agent_root.agent_id)).to eq([])
+    expect(journal_repository.head(journal_agent_root.agent_id)).to eq(0)
+  end
+
+  it "deletes the Agent Journal" do
+    journal_repository.append(
+      journal_agent_root.agent_id,
+      expected_position: 0,
+      records: [build_contract_journal_record(agent_id: journal_agent_root.agent_id)]
+    )
+    journal_repository.delete(journal_agent_root.agent_id)
+
+    expect(journal_repository.read(journal_agent_root.agent_id)).to eq([])
+    expect(journal_repository.head(journal_agent_root.agent_id)).to eq(0)
+  end
+end

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

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+RSpec.shared_examples "a Persistence backend" do
+  let(:backend_agent_root) do
+    Phronomy::Agent::AgentRoot.create(
+      agent_id: "backend-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+  end
+
+  def build_backend_execution(root)
+    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: record)
+  end
+
+  it "advertises every required capability" do
+    Phronomy::Persistence::REQUIRED_CAPABILITIES.each do |name, required_value|
+      expect(persistence.capabilities[name]).to eq(required_value)
+    end
+  end
+
+  it "yields a transaction view that exposes the complete durable SPI" do
+    persistence.transaction do |tx|
+      expect(tx).to respond_to(
+        :contents,
+        :agents,
+        :journals,
+        :executions,
+        :workflow_states,
+        :assert_agent_watermark!
+      )
+    end
+  end
+
+  it "returns the transaction block result" do
+    expect(persistence.transaction { |_tx| :contract_result }).to eq(:contract_result)
+  end
+
+  it "commits changes across durable repositories as one transaction" do
+    root = backend_agent_root
+    execution = build_backend_execution(root)
+    workflow_id = "workflow-#{SecureRandom.uuid}"
+    content_id = nil
+
+    persistence.transaction do |tx|
+      content_id = tx.contents.put_text("committed")
+      tx.agents.create(root)
+      appended = tx.journals.append(
+        root.agent_id,
+        expected_position: 0,
+        records: [
+          Phronomy::Agent::JournalRecord.new(
+            agent_id: root.agent_id,
+            kind: :knowledge,
+            channel: :context,
+            role: :user,
+            content_ref: content_id,
+            context_candidate: true
+          )
+        ]
+      )
+      tx.executions.create_active(execution)
+      tx.workflow_states.save(
+        workflow_id,
+        expected_revision: nil,
+        snapshot: {fields: {value: "committed"}, phase: "pause"}
+      )
+
+      updated_root = root.with(
+        agent_revision: 1,
+        journal_position: appended.length,
+        lifecycle_status: :active
+      )
+      tx.agents.save(root.agent_id, expected_revision: 0, root: updated_root)
+    end
+
+    expect(persistence.contents.exist?(content_id)).to be(true)
+    expect(persistence.agents.load(root.agent_id).agent_revision).to eq(1)
+    expect(persistence.journals.head(root.agent_id)).to eq(1)
+    expect(persistence.executions.load(execution.execution_id).execution_id)
+      .to eq(execution.execution_id)
+    expect(persistence.workflow_states.load(workflow_id)).not_to be_nil
+  end
+
+  it "rolls back all durable repositories when the transaction block raises" do
+    root = backend_agent_root
+    execution = build_backend_execution(root)
+    workflow_id = "workflow-#{SecureRandom.uuid}"
+    content_id = nil
+
+    expect do
+      persistence.transaction do |tx|
+        content_id = tx.contents.put_text("temporary-#{SecureRandom.uuid}")
+        tx.agents.create(root)
+        tx.journals.append(
+          root.agent_id,
+          expected_position: 0,
+          records: [
+            Phronomy::Agent::JournalRecord.new(
+              agent_id: root.agent_id,
+              kind: :knowledge,
+              channel: :context,
+              role: :user,
+              content_ref: content_id,
+              context_candidate: true
+            )
+          ]
+        )
+        tx.executions.create_active(execution)
+        tx.workflow_states.save(
+          workflow_id,
+          expected_revision: nil,
+          snapshot: {fields: {value: "temporary"}, phase: "pause"}
+        )
+        raise "rollback-contract"
+      end
+    end.to raise_error("rollback-contract")
+
+    expect(persistence.contents.exist?(content_id)).to be(false)
+    expect do
+      persistence.agents.load(root.agent_id)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+    expect(persistence.journals.head(root.agent_id)).to eq(0)
+    expect do
+      persistence.executions.load(execution.execution_id)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+    expect(persistence.workflow_states.load(workflow_id)).to be_nil
+  end
+
+  it "accepts the current Agent revision and Journal position watermark" do
+    root = backend_agent_root
+    persistence.agents.create(root)
+
+    expect(
+      persistence.assert_agent_watermark!(
+        agent_id: root.agent_id,
+        agent_revision: root.agent_revision,
+        journal_position: root.journal_position
+      )
+    ).to be(true)
+  end
+
+  it "raises ConflictError when the durable Agent revision has advanced" do
+    root = backend_agent_root
+    persistence.agents.create(root)
+    advanced = root.with(agent_revision: 1)
+    persistence.agents.save(root.agent_id, expected_revision: 0, root: advanced)
+
+    expect do
+      persistence.assert_agent_watermark!(
+        agent_id: root.agent_id,
+        agent_revision: 0,
+        journal_position: 0
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "raises ConflictError when the durable Journal position has advanced" do
+    root = backend_agent_root
+    persistence.agents.create(root)
+    persistence.journals.append(
+      root.agent_id,
+      expected_position: 0,
+      records: [
+        Phronomy::Agent::JournalRecord.new(
+          agent_id: root.agent_id,
+          kind: :knowledge,
+          channel: :context,
+          role: :user,
+          context_candidate: true
+        )
+      ]
+    )
+
+    expect do
+      persistence.assert_agent_watermark!(
+        agent_id: root.agent_id,
+        agent_revision: 0,
+        journal_position: 0
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rolls back earlier writes when a watermark precondition fails" do
+    root = backend_agent_root
+    persistence.agents.create(root)
+    advanced = root.with(agent_revision: 1)
+    persistence.agents.save(root.agent_id, expected_revision: 0, root: advanced)
+    temporary_content_id = nil
+
+    expect do
+      persistence.transaction do |tx|
+        temporary_content_id = tx.contents.put_text(
+          "watermark-rollback-#{SecureRandom.uuid}"
+        )
+        tx.assert_agent_watermark!(
+          agent_id: root.agent_id,
+          agent_revision: 0,
+          journal_position: 0
+        )
+      end
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+
+    expect(persistence.contents.exist?(temporary_content_id)).to be(false)
+  end
+end