phronomy 0.26.0 → 0.27.0

data/lib/phronomy/agent/persistence/agent_repository.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Persistence
+      # Owns Agent root encoding and validates returned storage metadata.
+      # @api private
+      class AgentRepository
+        def initialize(view) = @view = view
+
+        def create(root)
+          record = Codec.encode_agent_root(root)
+          @view.atomic do |bound|
+            entry = bound.records(StorageSchema::ROOTS).insert(key: root.agent_id.to_s,
+              revision: Integer(root.agent_revision), attributes: {}, record: record)
+            decode(entry, root.agent_id, revision: root.agent_revision)
+          end
+        end
+
+        def load(agent_id)
+          value = @view.atomic do |bound|
+            entry = bound.records(StorageSchema::ROOTS).read(agent_id.to_s)
+            entry && decode(entry, agent_id)
+          end
+          value || raise(Phronomy::Storage::NotFoundError, "Agent not found: #{agent_id}")
+        end
+
+        def save(agent_id, expected_revision:, root:)
+          expected = Integer(expected_revision)
+          revision = Integer(root.agent_revision)
+          raise Phronomy::Storage::ConflictError, "root save must advance revision exactly once" unless revision == expected + 1
+          unless root.agent_id.to_s == agent_id.to_s
+            raise Phronomy::Storage::SerializationError, "Agent root identity mismatch"
+          end
+          record = Codec.encode_agent_root(root)
+          @view.atomic do |bound|
+            entry = bound.records(StorageSchema::ROOTS).replace(key: agent_id.to_s,
+              expected_revision: expected, next_revision: revision, attributes: {}, record: record)
+            decode(entry, agent_id, revision: revision)
+          end
+        end
+
+        def delete(agent_id)
+          @view.records(StorageSchema::ROOTS).delete(key: agent_id.to_s)
+        end
+
+        private
+
+        def decode(entry, agent_id, revision: nil)
+          root = Codec.decode_agent_root(entry.record)
+          valid = entry.key == agent_id.to_s && root.agent_id == entry.key &&
+            root.agent_revision == entry.revision && (!revision || revision == entry.revision)
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Agent identity/revision"
+          end
+          root
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/persistence/codec.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Persistence
+      # Current-format record schemas and conversion for this domain.
+      # @api private
+      module Codec
+        extend Phronomy::Storage::RecordCodec
+
+        AGENT_ROOT_RECORD_TYPE = "phronomy.agent_root"
+        AGENT_ROOT_FORMAT_VERSION = "0.1"
+        AGENT_EXECUTION_RECORD_TYPE = "phronomy.agent_execution"
+        AGENT_EXECUTION_FORMAT_VERSION = "0.1"
+        JOURNAL_RECORD_TYPE = "phronomy.journal_record"
+        JOURNAL_FORMAT_VERSION = "0.1"
+        AGENT_ROOT_KEYS = %w[
+          agent_id agent_definition_id agent_definition_version agent_revision
+          context_revision journal_position lifecycle_status transcript_generation
+          created_at updated_at metadata
+        ].freeze
+
+        AGENT_EXECUTION_KEYS = %w[
+          execution_id agent_id execution_revision status phase
+          base_agent_revision base_context_revision base_journal_position
+          working_records llm_calls approval_request result_ref error_ref
+          created_at updated_at terminal_reason metadata
+        ].freeze
+
+        JOURNAL_RECORD_KEYS = %w[
+          record_id agent_id sequence execution_id llm_call_id kind channel role
+          content_ref parent_id causation_id visibility context_generation
+          context_candidate occurred_at metadata
+        ].freeze
+
+        LLM_CALL_RECORD_KEYS = %w[
+          llm_call_id execution_id sequence status manifest_ref output_ref
+          error_ref usage_ref started_at completed_at metadata
+        ].freeze
+
+        APPROVAL_REQUEST_KEYS = %w[id execution_id items created_at].freeze
+
+        APPROVAL_REQUEST_OPTIONAL_KEYS = %w[approved].freeze
+
+        APPROVAL_ITEM_KEYS = %w[
+          tool_invocation_id tool_call_id tool_name arguments facts reason origin metadata
+        ].freeze
+
+        module_function
+
+        def encode_handoff_state(value)
+          payload = value.to_h
+          Phronomy::Agent::HandoffState.from_h(payload)
+          build_record("phronomy.handoff_state", "0.1", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode HandoffState", error)
+        end
+
+        def decode_handoff_state(record)
+          payload = current_payload!(record, record_type: "phronomy.handoff_state",
+            format_version: "0.1", keys: Phronomy::Agent::HandoffState::ATTRIBUTES, label: "HandoffState")
+          Phronomy::Agent::HandoffState.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode HandoffState", error)
+        end
+
+        def encode_agent_root(root)
+          payload = top_level_string_keys(root.to_h, label: "AgentRoot payload")
+          payload["lifecycle_status"] = root.lifecycle_status.to_s
+          validate_agent_root_payload!(payload)
+          build_record(AGENT_ROOT_RECORD_TYPE, AGENT_ROOT_FORMAT_VERSION, payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode AgentRoot", error)
+        end
+
+        def decode_agent_root(record)
+          payload = current_payload!(
+            record,
+            record_type: AGENT_ROOT_RECORD_TYPE,
+            format_version: AGENT_ROOT_FORMAT_VERSION,
+            keys: AGENT_ROOT_KEYS,
+            label: "AgentRoot payload"
+          )
+          validate_agent_root_payload!(payload)
+          Phronomy::Agent::AgentRoot.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode AgentRoot", error)
+        end
+
+        def encode_agent_execution(execution)
+          payload = top_level_string_keys(execution.to_h, label: "AgentExecution payload")
+          payload["status"] = execution.status.to_s
+          payload["phase"] = execution.phase.to_s
+          payload["working_records"] = execution.working_records.map do |record|
+            journal_payload(record, require_sequence: false)
+          end
+          payload["llm_calls"] = execution.llm_calls.map do |call|
+            llm_call_payload(call)
+          end
+          validate_agent_execution_payload!(payload)
+          build_record(
+            AGENT_EXECUTION_RECORD_TYPE,
+            AGENT_EXECUTION_FORMAT_VERSION,
+            payload
+          )
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode AgentExecution", error)
+        end
+
+        def decode_agent_execution(record)
+          payload = current_payload!(
+            record,
+            record_type: AGENT_EXECUTION_RECORD_TYPE,
+            format_version: AGENT_EXECUTION_FORMAT_VERSION,
+            keys: AGENT_EXECUTION_KEYS,
+            label: "AgentExecution payload"
+          )
+          validate_agent_execution_payload!(payload)
+          Phronomy::Agent::AgentExecution.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode AgentExecution", error)
+        end
+
+        def encode_journal_record(journal_record)
+          payload = journal_payload(journal_record, require_sequence: true)
+          build_record(JOURNAL_RECORD_TYPE, JOURNAL_FORMAT_VERSION, payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode JournalRecord", error)
+        end
+
+        def decode_journal_record(record)
+          payload = current_payload!(
+            record,
+            record_type: JOURNAL_RECORD_TYPE,
+            format_version: JOURNAL_FORMAT_VERSION,
+            keys: JOURNAL_RECORD_KEYS,
+            label: "JournalRecord payload"
+          )
+          validate_journal_payload!(payload, label: "JournalRecord payload", require_sequence: true)
+          Phronomy::Agent::JournalRecord.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode JournalRecord", error)
+        end
+
+        def validate_agent_root_payload!(payload)
+          validate_exact_keys!(payload, AGENT_ROOT_KEYS, label: "AgentRoot payload")
+          require_nonempty_string!(payload, "agent_id", label: "AgentRoot payload")
+          require_nonempty_string!(payload, "agent_definition_id", label: "AgentRoot payload")
+          require_integer!(payload, "agent_definition_version", label: "AgentRoot payload")
+          require_nonnegative_integer!(payload, "agent_revision", label: "AgentRoot payload")
+          require_nonnegative_integer!(payload, "context_revision", label: "AgentRoot payload")
+          require_nonnegative_integer!(payload, "journal_position", label: "AgentRoot payload")
+          require_enum_string!(
+            payload,
+            "lifecycle_status",
+            Phronomy::Agent::AgentRoot::LIFECYCLE_STATUSES.map(&:to_s),
+            label: "AgentRoot payload"
+          )
+          require_nonnegative_integer!(payload, "transcript_generation", label: "AgentRoot payload")
+          require_nonempty_string!(payload, "created_at", label: "AgentRoot payload")
+          require_nonempty_string!(payload, "updated_at", label: "AgentRoot payload")
+          require_canonical_hash!(payload, "metadata", label: "AgentRoot payload")
+          payload
+        end
+
+        def validate_agent_execution_payload!(payload)
+          validate_exact_keys!(payload, AGENT_EXECUTION_KEYS, label: "AgentExecution payload")
+          require_nonempty_string!(payload, "execution_id", label: "AgentExecution payload")
+          require_nonempty_string!(payload, "agent_id", label: "AgentExecution payload")
+          require_nonnegative_integer!(payload, "execution_revision", label: "AgentExecution payload")
+          require_enum_string!(
+            payload,
+            "status",
+            Phronomy::Agent::AgentExecution::TRANSITIONS.keys.map(&:to_s),
+            label: "AgentExecution payload"
+          )
+          require_nonempty_string!(payload, "phase", label: "AgentExecution payload")
+          require_nonnegative_integer!(payload, "base_agent_revision", label: "AgentExecution payload")
+          require_nonnegative_integer!(payload, "base_context_revision", label: "AgentExecution payload")
+          require_nonnegative_integer!(payload, "base_journal_position", label: "AgentExecution payload")
+          require_optional_string!(payload, "result_ref", label: "AgentExecution payload")
+          require_optional_string!(payload, "error_ref", label: "AgentExecution payload")
+          require_nonempty_string!(payload, "created_at", label: "AgentExecution payload")
+          require_nonempty_string!(payload, "updated_at", label: "AgentExecution payload")
+          require_optional_string!(payload, "terminal_reason", label: "AgentExecution payload")
+          require_canonical_hash!(payload, "metadata", label: "AgentExecution payload")
+
+          working_records = payload.fetch("working_records")
+          unless working_records.is_a?(Array)
+            raise Phronomy::Storage::SerializationError,
+              "AgentExecution payload working_records must be an Array"
+          end
+          working_records.each_with_index do |record, index|
+            validate_journal_payload!(
+              record,
+              label: "AgentExecution working_records[#{index}]",
+              require_sequence: false
+            )
+            record_agent_id = record.fetch("agent_id")
+            unless record_agent_id == payload.fetch("agent_id")
+              raise Phronomy::Storage::SerializationError,
+                "AgentExecution working_records[#{index}] agent_id mismatch"
+            end
+            record_execution_id = record.fetch("execution_id")
+            if record_execution_id && record_execution_id != payload.fetch("execution_id")
+              raise Phronomy::Storage::SerializationError,
+                "AgentExecution working_records[#{index}] execution_id mismatch"
+            end
+          end
+
+          llm_calls = payload.fetch("llm_calls")
+          unless llm_calls.is_a?(Array)
+            raise Phronomy::Storage::SerializationError,
+              "AgentExecution payload llm_calls must be an Array"
+          end
+          llm_calls.each_with_index do |call, index|
+            validate_llm_call_payload!(call, label: "AgentExecution llm_calls[#{index}]")
+            unless call.fetch("execution_id") == payload.fetch("execution_id")
+              raise Phronomy::Storage::SerializationError,
+                "AgentExecution llm_calls[#{index}] execution_id mismatch"
+            end
+          end
+
+          validate_approval_request!(
+            payload.fetch("approval_request"),
+            execution_id: payload.fetch("execution_id")
+          )
+          payload
+        end
+
+        def validate_journal_payload!(payload, label:, require_sequence:)
+          validate_exact_keys!(payload, JOURNAL_RECORD_KEYS, label: label)
+          require_nonempty_string!(payload, "record_id", label: label)
+          require_nonempty_string!(payload, "agent_id", label: label)
+          sequence = payload.fetch("sequence")
+          if require_sequence
+            unless sequence.is_a?(Integer) && sequence.positive?
+              raise Phronomy::Storage::SerializationError,
+                "#{label} sequence must be a positive Integer"
+            end
+          elsif !(sequence.nil? || (sequence.is_a?(Integer) && sequence.positive?))
+            raise Phronomy::Storage::SerializationError,
+              "#{label} sequence must be nil or a positive Integer"
+          end
+          require_optional_string!(payload, "execution_id", label: label)
+          require_optional_string!(payload, "llm_call_id", label: label)
+          require_nonempty_string!(payload, "kind", label: label)
+          require_nonempty_string!(payload, "channel", label: label)
+          require_optional_string!(payload, "role", label: label)
+          require_optional_string!(payload, "content_ref", label: label)
+          require_optional_string!(payload, "parent_id", label: label)
+          require_optional_string!(payload, "causation_id", label: label)
+          require_nonempty_string!(payload, "visibility", label: label)
+          require_nonnegative_integer!(payload, "context_generation", label: label)
+          require_boolean!(payload, "context_candidate", label: label)
+          require_nonempty_string!(payload, "occurred_at", label: label)
+          require_canonical_hash!(payload, "metadata", label: label)
+          payload
+        end
+
+        def validate_llm_call_payload!(payload, label:)
+          validate_exact_keys!(payload, LLM_CALL_RECORD_KEYS, label: label)
+          require_nonempty_string!(payload, "llm_call_id", label: label)
+          require_nonempty_string!(payload, "execution_id", label: label)
+          require_positive_integer!(payload, "sequence", label: label)
+          require_enum_string!(
+            payload,
+            "status",
+            Phronomy::Agent::LLMCallRecord::STATUSES.map(&:to_s),
+            label: label
+          )
+          require_nonempty_string!(payload, "manifest_ref", label: label)
+          require_optional_string!(payload, "output_ref", label: label)
+          require_optional_string!(payload, "error_ref", label: label)
+          require_optional_string!(payload, "usage_ref", label: label)
+          require_nonempty_string!(payload, "started_at", label: label)
+          require_optional_string!(payload, "completed_at", label: label)
+          require_canonical_hash!(payload, "metadata", label: label)
+          payload
+        end
+
+        def validate_approval_request!(request, execution_id:)
+          return if request.nil?
+
+          validate_allowed_keys!(
+            request,
+            required_keys: APPROVAL_REQUEST_KEYS,
+            optional_keys: APPROVAL_REQUEST_OPTIONAL_KEYS,
+            label: "approval_request"
+          )
+          require_nonempty_string!(request, "id", label: "approval_request")
+          require_nonempty_string!(request, "execution_id", label: "approval_request")
+          unless request.fetch("execution_id") == execution_id
+            raise Phronomy::Storage::SerializationError,
+              "approval_request execution_id mismatch"
+          end
+          require_nonempty_string!(request, "created_at", label: "approval_request")
+          if request.key?("approved") && !boolean?(request.fetch("approved"))
+            raise Phronomy::Storage::SerializationError,
+              "approval_request approved must be true or false"
+          end
+
+          items = request.fetch("items")
+          unless items.is_a?(Array) && !items.empty?
+            raise Phronomy::Storage::SerializationError,
+              "approval_request items must be a non-empty Array"
+          end
+          items.each_with_index do |item, index|
+            item_label = "approval_request items[#{index}]"
+            validate_exact_keys!(item, APPROVAL_ITEM_KEYS, label: item_label)
+            require_nonempty_string!(item, "tool_invocation_id", label: item_label)
+            require_optional_string!(item, "tool_call_id", label: item_label)
+            require_nonempty_string!(item, "tool_name", label: item_label)
+            require_canonical_hash!(item, "arguments", label: item_label)
+            require_canonical_hash!(item, "facts", label: item_label)
+            require_optional_string!(item, "reason", label: item_label)
+            require_nonempty_string!(item, "origin", label: item_label)
+            require_canonical_hash!(item, "metadata", label: item_label)
+          end
+          request
+        end
+
+        def journal_payload(record, require_sequence:)
+          payload = top_level_string_keys(record.to_h, label: "JournalRecord payload")
+          %w[kind channel role visibility].each do |key|
+            value = payload[key]
+            payload[key] = value.to_s if value
+          end
+          validate_journal_payload!(payload, label: "JournalRecord payload", require_sequence: require_sequence)
+          payload
+        end
+
+        def llm_call_payload(call)
+          payload = top_level_string_keys(call.to_h, label: "LLMCallRecord payload")
+          payload["status"] = call.status.to_s
+          validate_llm_call_payload!(payload, label: "LLMCallRecord payload")
+          payload
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/persistence/execution_repository.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Persistence
+      # Owns execution activity, ownership, admission and durable record encoding.
+      # @api private
+      class ExecutionRepository
+        def initialize(view) = @view = view
+
+        def create_active(execution)
+          raise Phronomy::Storage::SerializationError, "create_active requires an active AgentExecution" unless execution.active?
+          record = Codec.encode_agent_execution(execution)
+          admission do
+            @view.atomic do |bound|
+              entry = bound.records(StorageSchema::EXECUTIONS).insert(key: execution.execution_id.to_s,
+                revision: Integer(execution.execution_revision), attributes: attributes(execution), record: record)
+              decode(entry, execution.execution_id, owner: execution.agent_id,
+                revision: execution.execution_revision, active: true)
+            end
+          end
+        end
+
+        def load(execution_id)
+          value = @view.atomic do |bound|
+            entry = bound.records(StorageSchema::EXECUTIONS).read(execution_id.to_s)
+            entry && decode(entry, execution_id)
+          end
+          value || raise(Phronomy::Storage::NotFoundError, "Execution not found: #{execution_id}")
+        end
+
+        def save(execution_id, expected_revision:, execution:)
+          expected = Integer(expected_revision)
+          revision = Integer(execution.execution_revision)
+          raise Phronomy::Storage::ConflictError, "execution save must advance revision exactly once" unless revision == expected + 1
+          unless execution.execution_id.to_s == execution_id.to_s
+            raise Phronomy::Storage::SerializationError, "Execution identity mismatch"
+          end
+          record = Codec.encode_agent_execution(execution)
+          admission do
+            @view.atomic do |bound|
+              entry = bound.records(StorageSchema::EXECUTIONS).replace(key: execution_id.to_s,
+                expected_revision: expected, next_revision: revision, attributes: attributes(execution),
+                expected_attributes: {}, record: record)
+              decode(entry, execution_id, owner: execution.agent_id, revision: revision, active: execution.active?)
+            end
+          end
+        end
+
+        def list_active(agent_id)
+          @view.atomic do |bound|
+            bound.records(StorageSchema::EXECUTIONS).scan(index: :owner_active,
+              equals: {owner: agent_id.to_s, active: true}).map { |entry| decode(entry, entry.key, owner: agent_id, active: true) }.freeze
+          end
+        end
+
+        def list(agent_id, after: nil, limit: 100)
+          raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
+          @view.atomic do |bound|
+            bound.records(StorageSchema::EXECUTIONS).scan(index: :owner, equals: {owner: agent_id.to_s},
+              after: after&.to_s, limit: limit).map { |entry| decode(entry, entry.key, owner: agent_id) }.freeze
+          end
+        end
+
+        def delete(execution_id)
+          @view.records(StorageSchema::EXECUTIONS).delete(key: execution_id.to_s)
+        end
+
+        def delete_for_agent(agent_id)
+          @view.records(StorageSchema::EXECUTIONS).delete_matching(index: :owner, equals: {owner: agent_id.to_s})
+        end
+
+        def assert_idle!(agent_id)
+          condition = Phronomy::Storage::Condition::NoRows.new(resource: StorageSchema::EXECUTIONS,
+            index: :owner_active, equals: {owner: agent_id.to_s, active: true})
+          @view.check!(guards: [Phronomy::Storage::GuardRef.new(resource: StorageSchema::ROOTS, key: agent_id.to_s)],
+            conditions: [condition])
+        rescue Phronomy::Storage::ConditionFailedError => error
+          raise unless error.condition.equal?(condition)
+          raise Phronomy::AgentBusyError, error.message
+        end
+
+        private
+
+        def attributes(execution) = {owner: execution.agent_id.to_s, active: execution.active?}
+
+        def admission
+          yield
+        rescue Phronomy::Storage::UniqueConstraintError => error
+          raise unless error.resource == StorageSchema::EXECUTIONS.id && error.constraint == :one_active_owner
+          raise Phronomy::AgentBusyError, error.message
+        end
+
+        def decode(entry, execution_id, owner: nil, revision: nil, active: nil)
+          execution = Codec.decode_agent_execution(entry.record)
+          valid = entry.key == execution_id.to_s && execution.execution_id == entry.key &&
+            execution.execution_revision == entry.revision && attributes(execution) == entry.attributes &&
+            (!owner || execution.agent_id == owner.to_s) && (!revision || execution.execution_revision == revision) &&
+            (active.nil? || execution.active? == active)
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Agent Execution identity/metadata"
+          end
+          execution
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/persistence/handoff_state_repository.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Persistence
+      # Owns Handoff state encoding and the initial revision.
+      # @api private
+      class HandoffStateRepository
+        def initialize(view) = @view = view
+
+        def load(main_agent_id)
+          @view.atomic do |bound|
+            entry = bound.records(StorageSchema::HANDOFF_STATES).read(main_agent_id.to_s)
+            entry && decode(entry, main_agent_id)
+          end
+        end
+
+        def save(main_agent_id, expected_revision:, state:)
+          expected = expected_revision.nil? ? nil : Integer(expected_revision)
+          revision = expected.nil? ? 1 : expected + 1
+          unless state.main_agent_id == main_agent_id.to_s && state.handoff_revision == revision
+            raise Phronomy::Storage::SerializationError, "Handoff identity/revision mismatch"
+          end
+          record = Codec.encode_handoff_state(state)
+          @view.atomic do |bound|
+            records = bound.records(StorageSchema::HANDOFF_STATES)
+            values = {key: main_agent_id.to_s, attributes: {active_agent_id: state.active_agent_id}, record: record}
+            entry = if expected.nil?
+              records.insert(**values, revision: revision)
+            else
+              records.replace(**values, expected_revision: expected, next_revision: revision)
+            end
+            decode(entry, main_agent_id, revision: revision)
+          end
+        rescue Phronomy::Storage::NotFoundError => error
+          raise Phronomy::Storage::ConflictError, error.message
+        end
+
+        def delete(main_agent_id, expected_revision:)
+          @view.records(StorageSchema::HANDOFF_STATES).delete(key: main_agent_id.to_s, expected_revision: Integer(expected_revision))
+        end
+
+        private
+
+        def decode(entry, main_agent_id, revision: nil)
+          state = Codec.decode_handoff_state(entry.record)
+          valid = entry.key == main_agent_id.to_s && state.main_agent_id == entry.key &&
+            state.handoff_revision == entry.revision && (!revision || revision == entry.revision) &&
+            entry.attributes == {active_agent_id: state.active_agent_id}
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Handoff identity/revision"
+          end
+          state
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/persistence/journal_repository.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Persistence
+      # Assigns domain sequence numbers and validates opaque stream entries.
+      # @api private
+      class JournalRepository
+        def initialize(view) = @view = view
+
+        def append(agent_id, expected_position:, records:)
+          expected = Integer(expected_position)
+          entries = Array(records).each_with_index.map do |record, index|
+            unless record.agent_id.to_s == agent_id.to_s
+              raise Phronomy::Storage::SerializationError, "Journal record Agent mismatch"
+            end
+            sequenced = record.with_sequence(expected + index + 1)
+            Phronomy::Storage::Entry::Append.new(id: sequenced.record_id.to_s, record: Codec.encode_journal_record(sequenced))
+          end
+          @view.atomic do |bound|
+            stored = bound.streams(StorageSchema::JOURNAL).append(stream: agent_id.to_s,
+              expected_head: expected, entries: entries)
+            decode(stored, agent_id, after: expected)
+          end
+        end
+
+        def read(agent_id, after: nil, limit: nil)
+          position = after.nil? ? 0 : Integer(after)
+          count = limit.nil? ? nil : Integer(limit)
+          @view.atomic do |bound|
+            stored = (count == 0) ? [] : bound.streams(StorageSchema::JOURNAL).read(stream: agent_id.to_s, after: position, limit: count)
+            decode(stored, agent_id, after: position)
+          end
+        end
+
+        def head(agent_id) = @view.streams(StorageSchema::JOURNAL).head(stream: agent_id.to_s)
+        def delete(agent_id) = @view.streams(StorageSchema::JOURNAL).delete(stream: agent_id.to_s)
+
+        private
+
+        def decode(entries, agent_id, after:)
+          entries.each_with_index.map do |entry, index|
+            record = Codec.decode_journal_record(entry.record)
+            unless record.agent_id == agent_id.to_s && record.record_id == entry.id &&
+                record.sequence == entry.position && entry.position == after + index + 1
+              raise Phronomy::Storage::SerializationError, "backend returned another Journal identity/sequence"
+            end
+            record
+          end.freeze
+        end
+      end
+    end
+  end
+end