phronomy 0.22.0 → 0.23.0

data/lib/phronomy/persistence/migration/initial_format_migration.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Persistence
+    module Migration
+      # Explicit logical conversion from the pre-S3 unversioned representations
+      # present at the ACS-06 fixed base to the initial 0.1 durable formats.
+      #
+      # This module does not scan a database or write records. A backend-specific
+      # migration runner is responsible for physical enumeration, transactions,
+      # and replacement. Normal Runtime load never calls these methods.
+      #
+      # @api public
+      module InitialFormatMigration
+        PRE_S3_AGENT_ROOT_KEYS = Phronomy::Agent::AgentRoot::ATTRIBUTES.map(&:to_s).freeze
+        PRE_S3_AGENT_EXECUTION_KEYS = Phronomy::Agent::AgentExecution::ATTRIBUTES.map(&:to_s).freeze
+        PRE_S3_JOURNAL_KEYS = Phronomy::Agent::JournalRecord::ATTRIBUTES.map(&:to_s).freeze
+        PRE_S3_LLM_CALL_KEYS = Phronomy::Agent::LLMCallRecord::ATTRIBUTES.map(&:to_s).freeze
+        PRE_S3_APPROVAL_REQUIRED_KEYS = %w[id items created_at].freeze
+        PRE_S3_APPROVAL_PARENT_KEYS = %w[execution_id agent_invocation_id].freeze
+        PRE_S3_APPROVAL_OPTIONAL_KEYS = %w[approved].freeze
+        PRE_S3_APPROVAL_ITEM_KEYS = %w[
+          tool_invocation_id tool_call_id tool_name arguments facts reason origin metadata
+        ].freeze
+
+        module_function
+
+        def agent_root(hash)
+          source = stringify_keys(hash)
+          validate_exact_keys!(
+            source,
+            PRE_S3_AGENT_ROOT_KEYS,
+            label: "pre-S3 AgentRoot"
+          )
+          DurableCodec.encode_agent_root(
+            Phronomy::Agent::AgentRoot.from_h(source)
+          )
+        rescue Phronomy::Persistence::SerializationError
+          raise
+        rescue => error
+          migration_error("AgentRoot", error)
+        end
+
+        def agent_execution(hash)
+          source = stringify_keys(hash)
+          validate_exact_keys!(
+            source,
+            PRE_S3_AGENT_EXECUTION_KEYS,
+            label: "pre-S3 AgentExecution"
+          )
+          source["working_records"] = Array(source.fetch("working_records")).map.with_index do |record, index|
+            normalize_legacy_journal_record(
+              record,
+              label: "pre-S3 AgentExecution working_records[#{index}]"
+            )
+          end
+          source["llm_calls"] = Array(source.fetch("llm_calls")).map.with_index do |call, index|
+            normalized = stringify_keys(call)
+            validate_exact_keys!(
+              normalized,
+              PRE_S3_LLM_CALL_KEYS,
+              label: "pre-S3 AgentExecution llm_calls[#{index}]"
+            )
+            normalized
+          end
+          source["approval_request"] = normalize_legacy_approval_request(
+            source["approval_request"],
+            execution_id: source.fetch("execution_id")
+          )
+          execution = Phronomy::Agent::AgentExecution.from_h(source)
+          DurableCodec.encode_agent_execution(execution)
+        rescue Phronomy::Persistence::SerializationError
+          raise
+        rescue => error
+          migration_error("AgentExecution", error)
+        end
+
+        def journal_record(hash)
+          source = normalize_legacy_journal_record(hash, label: "pre-S3 JournalRecord")
+          DurableCodec.encode_journal_record(
+            Phronomy::Agent::JournalRecord.from_h(source)
+          )
+        rescue Phronomy::Persistence::SerializationError
+          raise
+        rescue => error
+          migration_error("JournalRecord", error)
+        end
+
+        def workflow_state(workflow_instance_id:, revision:, snapshot:)
+          DurableCodec.encode_workflow_state(
+            workflow_instance_id: workflow_instance_id,
+            workflow_revision: Integer(revision),
+            snapshot: snapshot
+          )
+        rescue Phronomy::Persistence::SerializationError
+          raise
+        rescue => error
+          migration_error("Workflow state", error)
+        end
+
+        # LLMInputManifest is a ContentStore codec boundary, not a
+        # Persistence::DurableRecord. Its pre-CG-07 integer version 1 is migrated
+        # explicitly to the pre-1.0 string version "0.1".
+        def llm_input_manifest(hash)
+          source = stringify_keys(hash)
+          old_version = source.fetch("version")
+          unless old_version == 1 || old_version == "1"
+            raise Phronomy::Persistence::SerializationError,
+              "unsupported pre-S3 LLMInputManifest version: #{old_version.inspect}"
+          end
+          source["version"] = Phronomy::Agent::LLMInputManifest::VERSION
+          Phronomy::Agent::LLMInputManifest.from_h(source).to_h
+        rescue Phronomy::Persistence::SerializationError
+          raise
+        rescue => error
+          migration_error("LLMInputManifest", error)
+        end
+
+        def normalize_legacy_journal_record(hash, label:)
+          source = stringify_keys(hash)
+          validate_allowed_keys!(
+            source,
+            required_keys: PRE_S3_JOURNAL_KEYS,
+            optional_keys: ["correlation_id"],
+            label: label
+          )
+          source.delete("correlation_id")
+          source
+        end
+        private_class_method :normalize_legacy_journal_record
+
+        def normalize_legacy_approval_request(request, execution_id:)
+          return nil unless request
+
+          source = stringify_keys(request)
+          validate_allowed_keys!(
+            source,
+            required_keys: PRE_S3_APPROVAL_REQUIRED_KEYS,
+            optional_keys: PRE_S3_APPROVAL_PARENT_KEYS + PRE_S3_APPROVAL_OPTIONAL_KEYS,
+            label: "pre-S3 approval_request"
+          )
+          parents = PRE_S3_APPROVAL_PARENT_KEYS.select { |key| source.key?(key) }
+          unless parents.length == 1
+            raise Phronomy::Persistence::SerializationError,
+              "pre-S3 approval_request must contain exactly one parent identity, got #{parents.inspect}"
+          end
+
+          items = source.fetch("items")
+          unless items.is_a?(Array) && !items.empty?
+            raise Phronomy::Persistence::SerializationError,
+              "pre-S3 approval_request items must be a non-empty Array"
+          end
+          source["items"] = items.map.with_index do |item, index|
+            normalized = stringify_keys(item)
+            validate_exact_keys!(
+              normalized,
+              PRE_S3_APPROVAL_ITEM_KEYS,
+              label: "pre-S3 approval_request items[#{index}]"
+            )
+            normalized
+          end
+
+          if source.key?("agent_invocation_id")
+            source.delete("agent_invocation_id")
+            source["execution_id"] = execution_id.to_s
+          elsif source.fetch("execution_id").to_s != execution_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "pre-S3 approval_request execution_id does not match AgentExecution"
+          end
+          source
+        end
+        private_class_method :normalize_legacy_approval_request
+
+        def validate_allowed_keys!(hash, required_keys:, optional_keys:, label:)
+          actual = hash.keys.sort
+          missing = required_keys.sort - actual
+          unknown = actual - (required_keys + optional_keys).sort
+          return hash if missing.empty? && unknown.empty?
+
+          details = []
+          details << "missing=#{missing.inspect}" unless missing.empty?
+          details << "unknown=#{unknown.inspect}" unless unknown.empty?
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} schema mismatch (#{details.join(", ")})"
+        end
+        private_class_method :validate_allowed_keys!
+
+        def validate_exact_keys!(hash, expected_keys, label:)
+          validate_allowed_keys!(
+            hash,
+            required_keys: expected_keys,
+            optional_keys: [],
+            label: label
+          )
+        end
+        private_class_method :validate_exact_keys!
+
+        def stringify_keys(hash)
+          unless hash.is_a?(Hash)
+            raise Phronomy::Persistence::SerializationError,
+              "migration input must be a Hash"
+          end
+          hash.each_with_object({}) do |(key, value), result|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise Phronomy::Persistence::SerializationError,
+                "migration key must be String or Symbol, got #{key.class}"
+            end
+            string_key = key.to_s
+            if result.key?(string_key)
+              raise Phronomy::Persistence::SerializationError,
+                "duplicate migration key after normalization: #{string_key.inspect}"
+            end
+            result[string_key] = value
+          end
+        end
+        private_class_method :stringify_keys
+
+        def migration_error(label, error)
+          raise Phronomy::Persistence::SerializationError,
+            "cannot migrate pre-S3 #{label}: #{error.class}: #{error.message}"
+        end
+        private_class_method :migration_error
+      end
+    end
+  end
+end

data/lib/phronomy/persistence/repository_facades.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Persistence
+    # Runtime/domain-facing repositories layered over record-oriented Backend SPI
+    # repositories. Backend implementations never receive AgentRoot,
+    # AgentExecution, JournalRecord, or Workflow snapshot domain values directly.
+    #
+    # Backend repositories receive DurableRecord plus explicit identity/revision/
+    # admission metadata needed for indexing and compare-and-swap. They must not
+    # inspect DurableRecord#payload to rediscover those semantics.
+    #
+    # @api private
+    module RepositoryFacades
+      class Agents
+        def initialize(backend_repository)
+          @backend_repository = backend_repository
+        end
+
+        def create(root)
+          record = DurableCodec.encode_agent_root(root)
+          stored = @backend_repository.create(
+            agent_id: root.agent_id.to_s,
+            agent_revision: Integer(root.agent_revision),
+            record: record
+          )
+          decode_for_agent(stored, root.agent_id, revision: root.agent_revision)
+        end
+
+        def load(agent_id)
+          decode_for_agent(@backend_repository.load(agent_id.to_s), agent_id)
+        end
+
+        def save(agent_id, expected_revision:, root:)
+          expected = Integer(expected_revision)
+          next_revision = Integer(root.agent_revision)
+          unless next_revision == expected + 1
+            raise Phronomy::Persistence::ConflictError,
+              "agent save must advance revision exactly once: " \
+              "expected #{expected + 1}, got #{next_revision}"
+          end
+          unless root.agent_id.to_s == agent_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "Agent root identity mismatch: #{root.agent_id} != #{agent_id}"
+          end
+
+          record = DurableCodec.encode_agent_root(root)
+          stored = @backend_repository.save(
+            agent_id.to_s,
+            expected_revision: expected,
+            next_revision: next_revision,
+            record: record
+          )
+          decode_for_agent(stored, agent_id, revision: next_revision)
+        end
+
+        def delete(agent_id)
+          @backend_repository.delete(agent_id.to_s)
+        end
+
+        private
+
+        def decode_for_agent(record, agent_id, revision: nil)
+          root = DurableCodec.decode_agent_root(record)
+          unless root.agent_id == agent_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Agent root for #{root.agent_id.inspect}; expected #{agent_id.to_s.inspect}"
+          end
+          if revision && root.agent_revision != revision
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Agent revision #{root.agent_revision}; expected #{revision}"
+          end
+          root
+        end
+      end
+
+      class Journals
+        def initialize(backend_repository)
+          @backend_repository = backend_repository
+        end
+
+        def append(agent_id, expected_position:, records:)
+          expected = Integer(expected_position)
+          sequenced = Array(records).each_with_index.map do |record, index|
+            unless record.agent_id.to_s == agent_id.to_s
+              raise Phronomy::Persistence::SerializationError,
+                "Journal record Agent mismatch: #{record.agent_id} != #{agent_id}"
+            end
+            record.with_sequence(expected + index + 1)
+          end
+          encoded = sequenced.map { |record| DurableCodec.encode_journal_record(record) }
+          stored = @backend_repository.append(
+            agent_id.to_s,
+            expected_position: expected,
+            records: encoded,
+            record_ids: sequenced.map { |record| record.record_id.to_s }.freeze
+          )
+          decoded = Array(stored).map { |record| DurableCodec.decode_journal_record(record) }
+          validate_read!(decoded, agent_id, start_sequence: expected + 1)
+        end
+
+        def read(agent_id, after: nil, limit: nil)
+          after_value = after.nil? ? nil : Integer(after)
+          limit_value = limit.nil? ? nil : Integer(limit)
+          stored = @backend_repository.read(
+            agent_id.to_s,
+            after: after_value,
+            limit: limit_value
+          )
+          decoded = Array(stored).map { |record| DurableCodec.decode_journal_record(record) }
+          validate_read!(decoded, agent_id, start_sequence: (after_value || 0) + 1)
+        end
+
+        def head(agent_id)
+          Integer(@backend_repository.head(agent_id.to_s))
+        end
+
+        def delete(agent_id)
+          @backend_repository.delete(agent_id.to_s)
+        end
+
+        private
+
+        def validate_read!(records, agent_id, start_sequence:)
+          records.each_with_index do |record, index|
+            unless record.agent_id == agent_id.to_s
+              raise Phronomy::Persistence::SerializationError,
+                "backend returned Journal record for #{record.agent_id.inspect}; expected #{agent_id.to_s.inspect}"
+            end
+            expected_sequence = start_sequence + index
+            unless record.sequence == expected_sequence
+              raise Phronomy::Persistence::SerializationError,
+                "backend returned Journal sequence #{record.sequence.inspect}; expected #{expected_sequence}"
+            end
+          end
+          records.freeze
+        end
+      end
+
+      class Executions
+        def initialize(backend_repository)
+          @backend_repository = backend_repository
+        end
+
+        def create_active(execution)
+          unless execution.active?
+            raise Phronomy::Persistence::SerializationError,
+              "create_active requires an active AgentExecution"
+          end
+          record = DurableCodec.encode_agent_execution(execution)
+          stored = @backend_repository.create_active(
+            execution_id: execution.execution_id.to_s,
+            agent_id: execution.agent_id.to_s,
+            execution_revision: Integer(execution.execution_revision),
+            record: record
+          )
+          decode_for_execution(
+            stored,
+            execution.execution_id,
+            agent_id: execution.agent_id,
+            revision: execution.execution_revision,
+            active: true
+          )
+        end
+
+        def load(execution_id)
+          decode_for_execution(@backend_repository.load(execution_id.to_s), execution_id)
+        end
+
+        def save(execution_id, expected_revision:, execution:)
+          expected = Integer(expected_revision)
+          next_revision = Integer(execution.execution_revision)
+          unless next_revision == expected + 1
+            raise Phronomy::Persistence::ConflictError,
+              "execution save must advance revision exactly once: " \
+              "expected #{expected + 1}, got #{next_revision}"
+          end
+          unless execution.execution_id.to_s == execution_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "Execution identity mismatch: #{execution.execution_id} != #{execution_id}"
+          end
+
+          record = DurableCodec.encode_agent_execution(execution)
+          stored = @backend_repository.save(
+            execution_id.to_s,
+            expected_revision: expected,
+            next_revision: next_revision,
+            agent_id: execution.agent_id.to_s,
+            active: execution.active?,
+            record: record
+          )
+          decode_for_execution(
+            stored,
+            execution_id,
+            agent_id: execution.agent_id,
+            revision: next_revision,
+            active: execution.active?
+          )
+        end
+
+        def list_active(agent_id)
+          Array(@backend_repository.list_active(agent_id.to_s)).map do |record|
+            decode_for_execution(record, nil, agent_id: agent_id, active: true)
+          end.freeze
+        end
+
+        def delete(execution_id)
+          @backend_repository.delete(execution_id.to_s)
+        end
+
+        def delete_for_agent(agent_id)
+          @backend_repository.delete_for_agent(agent_id.to_s)
+        end
+
+        def assert_idle!(agent_id)
+          @backend_repository.assert_idle!(agent_id.to_s)
+        end
+
+        private
+
+        def decode_for_execution(record, execution_id, agent_id: nil, revision: nil, active: nil)
+          execution = DurableCodec.decode_agent_execution(record)
+          if execution_id && execution.execution_id != execution_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Execution #{execution.execution_id.inspect}; expected #{execution_id.to_s.inspect}"
+          end
+          if agent_id && execution.agent_id != agent_id.to_s
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Execution for Agent #{execution.agent_id.inspect}; expected #{agent_id.to_s.inspect}"
+          end
+          if revision && execution.execution_revision != revision
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Execution revision #{execution.execution_revision}; expected #{revision}"
+          end
+          if !active.nil? && execution.active? != active
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Execution active=#{execution.active?}; expected #{active}"
+          end
+          execution
+        end
+      end
+
+      class WorkflowStates
+        def initialize(backend_repository)
+          @backend_repository = backend_repository
+        end
+
+        def load(workflow_instance_id)
+          record = @backend_repository.load(workflow_instance_id.to_s)
+          return nil unless record
+
+          DurableCodec.decode_workflow_state(
+            record,
+            expected_workflow_instance_id: workflow_instance_id
+          )
+        end
+
+        def save(workflow_instance_id, expected_revision:, snapshot:)
+          expected = expected_revision.nil? ? nil : Integer(expected_revision)
+          next_revision = expected.nil? ? 1 : expected + 1
+          record = DurableCodec.encode_workflow_state(
+            workflow_instance_id: workflow_instance_id,
+            workflow_revision: next_revision,
+            snapshot: snapshot
+          )
+          stored = @backend_repository.save(
+            workflow_instance_id.to_s,
+            expected_revision: expected,
+            next_revision: next_revision,
+            record: record
+          )
+          decoded = DurableCodec.decode_workflow_state(
+            stored,
+            expected_workflow_instance_id: workflow_instance_id
+          )
+          unless decoded.fetch(:revision) == next_revision
+            raise Phronomy::Persistence::SerializationError,
+              "backend returned Workflow revision #{decoded.fetch(:revision)}; expected #{next_revision}"
+          end
+          decoded.fetch(:revision)
+        end
+
+        def delete(workflow_instance_id, expected_revision:)
+          @backend_repository.delete(
+            workflow_instance_id.to_s,
+            expected_revision: Integer(expected_revision)
+          )
+        end
+      end
+
+      # Transaction-scoped domain-facing Persistence view built from raw backend
+      # repositories. Backend implementations can use this through
+      # Persistence#build_transaction_view without duplicating facade logic.
+      class View
+        attr_reader :contents, :agents, :journals, :executions, :workflow_states
+
+        def initialize(contents:, agents:, journals:, executions:, workflow_states:, watermark:)
+          @contents = contents
+          @agents = Agents.new(agents)
+          @journals = Journals.new(journals)
+          @executions = Executions.new(executions)
+          @workflow_states = WorkflowStates.new(workflow_states)
+          @watermark = watermark
+        end
+
+        def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
+          @watermark.assert_agent_watermark!(
+            agent_id: agent_id.to_s,
+            agent_revision: Integer(agent_revision),
+            journal_position: Integer(journal_position)
+          )
+        end
+      end
+    end
+  end
+end