phronomy 0.18.0 → 0.20.0

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

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