phronomy 0.26.0 → 0.28.0

data/lib/phronomy/runtime_composition/configuration.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "../configuration/runtime_settings"
+require_relative "../agent/settings"
+require_relative "../workflow/execution/workflow_settings"
+require_relative "../tool/settings"
+require_relative "../tracing/settings"
+
+module Phronomy
+  # Application-facing configuration composes domain options and neutral runtime
+  # settings. Public accessors and constructor behavior stay unchanged.
+  class Configuration
+    extend Forwardable
+
+    DEFAULT_FACTORIES = {}
+    private_constant :DEFAULT_FACTORIES
+
+    # Bind fresh-instance factories once during application loading. Concrete
+    # component selection belongs to runtime_composition, not configuration.
+    # Applications replace instances through the existing configuration writers.
+    # @api private
+    def self.install_default_factories(tracer:, llm_adapter:)
+      DEFAULT_FACTORIES.replace(tracer: tracer, llm_adapter: llm_adapter).freeze
+      nil
+    end
+
+    attr_accessor :default_embedding_model, :multi_agent_store
+
+    # Preserve the public settings facade while each domain owns its values.
+    def_delegators :@__agent_settings, :default_model, :default_model=
+    def_delegators :@__agent_settings, :before_llm_input, :before_llm_input=
+    def_delegators :@__agent_settings, :agent_store, :agent_store=
+    def_delegators :@__agent_settings, :llm_adapter, :llm_adapter=
+    def_delegators :@__agent_settings, :stream_callback_error_policy, :stream_callback_error_policy=
+    def_delegators :@__agent_settings, :authorization_timeout, :authorization_timeout=
+    def_delegators :@__workflow_settings, :recursion_limit, :recursion_limit=
+    def_delegators :@__workflow_settings, :workflow_store, :workflow_store=
+    def_delegators :@__runtime_settings, :authorization_pool_size, :authorization_pool_size=
+    def_delegators :@__runtime_settings, :authorization_queue_size, :authorization_queue_size=
+
+    # @api private
+    attr_reader :__agent_settings, :__workflow_settings, :__tool_settings, :__tracing_settings
+
+    # Engine access is bound by the composition root, not by Engine itself.
+    # @api private
+    attr_reader :__runtime_settings
+
+    def tracer
+      @__tracing_settings.tracer
+    end
+
+    def tracer=(value)
+      @__tracing_settings.tracer = value
+    end
+
+    def trace_pii
+      @__tracing_settings.trace_pii
+    end
+
+    def trace_pii=(value)
+      @__tracing_settings.trace_pii = value
+    end
+
+    def logger
+      @__runtime_settings.logger
+    end
+
+    def logger=(value)
+      @__runtime_settings.logger = value
+    end
+
+    def tool_result_max_size
+      @__tool_settings.max_result_size
+    end
+
+    def tool_result_max_size=(value)
+      @__tool_settings.max_result_size = value
+    end
+
+    def event_loop_stop_grace_seconds
+      @__runtime_settings.event_loop_stop_grace_seconds
+    end
+
+    def event_loop_stop_grace_seconds=(value)
+      @__runtime_settings.event_loop_stop_grace_seconds = value
+    end
+
+    def event_loop_starvation_threshold_seconds
+      @__runtime_settings.event_loop_starvation_threshold_seconds
+    end
+
+    def event_loop_starvation_threshold_seconds=(value)
+      @__runtime_settings.event_loop_starvation_threshold_seconds = value
+    end
+
+    def event_loop_dispatch_threshold_seconds
+      @__runtime_settings.event_loop_dispatch_threshold_seconds
+    end
+
+    def event_loop_dispatch_threshold_seconds=(value)
+      @__runtime_settings.event_loop_dispatch_threshold_seconds = value
+    end
+
+    def offload_pool_size
+      @__runtime_settings.offload_pool_size
+    end
+
+    def offload_pool_size=(value)
+      @__runtime_settings.offload_pool_size = value
+    end
+
+    def offload_queue_size
+      @__runtime_settings.offload_queue_size
+    end
+
+    def offload_queue_size=(value)
+      @__runtime_settings.offload_queue_size = value
+    end
+
+    def initialize
+      @__workflow_settings = WorkflowSettings.new(recursion_limit: 25)
+      @__runtime_settings = RuntimeSettings.new
+      @__tool_settings = Tool::Settings.new
+      @__tracing_settings = Tracing::Settings.new(tracer: DEFAULT_FACTORIES.fetch(:tracer).call)
+      @__agent_settings = Agent::Settings.new(
+        llm_adapter: DEFAULT_FACTORIES.fetch(:llm_adapter).call,
+        stream_callback_error_policy: :report, authorization_timeout: 5
+      )
+      @multi_agent_store = nil
+    end
+
+    private
+
+    # A scoped configuration copy owns its scalar settings while retaining the
+    # same injected tracer/logger identities, just like the previous flat object.
+    def initialize_copy(original)
+      super
+      @__runtime_settings = original.__runtime_settings.dup
+      @__agent_settings = original.__agent_settings.dup
+      @__workflow_settings = original.__workflow_settings.dup
+      @__tool_settings = original.__tool_settings.dup
+      @__tracing_settings = original.__tracing_settings.dup
+    end
+  end
+end

data/lib/phronomy/runtime_composition/configuration_defaults.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Select concrete defaults at the application composition boundary. Each factory
+# runs during Configuration.new, not during binding; no Runtime is started here.
+# Explicitly loaded after Zeitwerk setup and before global configuration access.
+Phronomy::Configuration.install_default_factories(
+  tracer: -> { Phronomy::Tracing::NullTracer.new },
+  llm_adapter: -> { Phronomy::LLMAdapter::RubyLLM.new }
+)

data/lib/phronomy/runtime_composition/evaluation_defaults.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Binding creates no client, Configuration or Runtime. Resolve the configured
+# adapter for every score at the existing read point; do not cache the client.
+Phronomy::Testing::Eval::Scorer::LlmJudge.install_client_factory(
+  -> { Phronomy::LLMAdapter::AsyncClient.new(adapter: Phronomy.configuration.llm_adapter) }
+)

data/lib/phronomy/runtime_composition/execution_defaults.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Phronomy::Execution.backend_provider = -> { Phronomy::ExecutionBinding }
+
+Phronomy::ExecutionReceiver.install_binding(-> { Phronomy::ExecutionReceiverBinding })

data/lib/phronomy/runtime_composition/generation_defaults.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Select the existing default without constructing a parser during boot.
+Phronomy::GeneratorVerifier::DefaultParser.install_factory(
+  -> { Phronomy::OutputParser::JsonParser.new }
+)

data/lib/phronomy/runtime_composition/global_configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Global configuration access, replacement, and scoped overrides.
+# Explicitly loaded by the application entry point; not a common definition.
+module Phronomy
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def with_configuration
+      original = @configuration&.dup
+      yield configuration
+    ensure
+      @configuration = original
+    end
+  end
+end
+
+# The provider yields only the Engine-facing value object, never Configuration.
+# It is intentionally lazy and follows reset_configuration!/with_configuration.
+Phronomy::RuntimeSettings.install_provider { Phronomy.configuration.__runtime_settings }
+
+# Domain accessors are lazy too. Each returns only the owning domain's values
+# or operation, never the application Configuration or a captured snapshot.
+Phronomy::Agent::Settings.install_provider { Phronomy.configuration.__agent_settings }
+Phronomy::WorkflowSettings.install_provider { Phronomy.configuration.__workflow_settings }
+Phronomy::Tool::Settings.install_provider { Phronomy.configuration.__tool_settings }
+Phronomy::Tracing::Settings.install_provider { Phronomy.configuration.__tracing_settings }
+Phronomy::MultiAgent::Store.install_configured_provider { Phronomy.configuration.multi_agent_store }

data/lib/phronomy/runtime_composition/global_runtime.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Application lifecycle coordination across Runtime and global configuration.
+# Explicitly loaded by the application entry point; not an Engine primitive.
+module Phronomy
+  class << self
+    def reset_runtime!(timeout: configuration.event_loop_stop_grace_seconds)
+      previous_grace = @configuration&.event_loop_stop_grace_seconds
+      result = Runtime.reset_default!(timeout: timeout)
+
+      new_configuration = Configuration.new
+      if previous_grace
+        new_configuration.event_loop_stop_grace_seconds = previous_grace
+      end
+      @configuration = new_configuration
+      result
+    end
+  end
+end

data/lib/phronomy/runtime_composition/multi_agent_defaults.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Select stores and execution connections at the application composition
+# boundary, without constructing either during library loading.
+Phronomy::MultiAgent::TeamCoordinator.install_persistence_factory(
+  -> { Phronomy::PersistenceComposition.in_memory.multi_agent }
+)
+
+Phronomy::MultiAgent::ExecutionEnvironment.install_provider(-> { Phronomy::MultiAgent::EngineEnvironment.new })

data/lib/phronomy/runtime_composition/workflow_defaults.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Install a lazy provider without creating a Runtime or execution registry.
+Phronomy::WorkflowExecutionEnvironment.install_provider(-> { Phronomy::WorkflowEngineEnvironment.new })

data/lib/phronomy/storage/async/async_client.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Asynchronous execution of a synchronous raw storage backend.
+    #
+    # A transaction opens, runs and closes on one worker. Return values rather
+    # than transaction views: a bound view is closed when the block finishes.
+    # Timeout includes queue wait. Timeout/cancellation settles TaskResult but
+    # does not interrupt running I/O or guarantee rollback of a started write.
+    # Construction starts no Runtime; the default pool is resolved per operation.
+    # An explicitly injected pool remains owned by its caller.
+    #
+    # @api public
+    class AsyncClient
+      # @param backend [Storage::Backend] synchronous raw SPI 2 backend
+      # @param pool [Concurrency::OffloadPool, nil] optional execution pool
+      # @api public
+      def initialize(backend:, pool: nil)
+        Backend.validate_capabilities!(backend)
+        @backend = backend
+        @pool = pool
+      end
+
+      # Executes the entire transaction on one worker without waiting for queue
+      # capacity. Explicit nested backend transactions retain savepoint semantics.
+      #
+      # @param cancellation_token [Concurrency::CancellationToken, nil]
+      # @param timeout [Numeric, nil] operation-wide submit timeout
+      # @yieldparam view [Storage::View] view valid only within this transaction
+      # @return [Phronomy::TaskResult] the pool's original completion handle
+      # @api public
+      def transaction_async(cancellation_token: nil, timeout: nil, &operation)
+        raise ArgumentError, "transaction_async requires a block" unless operation
+
+        Phronomy::Execution.submit(pool: default_pool, timeout: timeout, cancellation_token: cancellation_token, on_full: :raise) do
+          @backend.transaction(&operation)
+        end
+      end
+
+      # Submit an existing domain-owned synchronous storage unit unchanged.
+      # It may already open transactions or perform reads/reconciliation. Do not
+      # add a transaction, timeout or cancellation condition around that unit.
+      # The owner supplies its current runtime's pool and applies the result.
+      #
+      # @api private
+      def self.submit(pool:, &operation)
+        raise ArgumentError, "storage submit requires a block" unless operation
+
+        Phronomy::Execution.submit(pool: pool, on_full: :raise, &operation)
+      end
+
+      private
+
+      def default_pool
+        @pool
+      end
+    end
+  end
+end

data/lib/phronomy/storage/backend.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Neutral storage SPI. Domain resource declarations are supplied by composition.
+    # @api public
+    class Backend
+      REQUIRED_CAPABILITIES = {spi_version: 2, atomic_resources: true,
+                               record_cas: true, stream_cas: true, conditional_unique: true,
+                               guarded_checks: true, nested_savepoints: true}.freeze
+      attr_reader :resources, :view
+
+      # @api public
+      def initialize(resources:)
+        unless resources.is_a?(Array) && resources.all? { |resource| resource.is_a?(Resource) }
+          raise UnsupportedBackendError, "SPI 2 requires Resource declarations"
+        end
+        @resources = resources.to_h { |resource| [resource.id, resource] }.freeze
+        raise UnsupportedBackendError, "duplicate resource identity" unless @resources.length == resources.length
+        @resources.each_value do |resource|
+          next unless resource.guard
+          anchor = @resources[resource.guard.fetch(:resource)]
+          raise UnsupportedBackendError, "guard must name a registered records resource" unless anchor && anchor.kind == :records
+        end
+        @view = View.new(self)
+      end
+
+      # Reject the previous eight-repository SPI before constructing domain wrappers.
+      # @api public
+      def self.validate_capabilities!(backend)
+        capabilities = backend.respond_to?(:capabilities) ? backend.capabilities : {}
+        missing = REQUIRED_CAPABILITIES.reject { |key, value| capabilities.is_a?(Hash) && capabilities[key] == value }
+        missing_methods = %i[view transaction transaction_open?].reject { |name| backend.respond_to?(name) }
+        unless missing.empty? && missing_methods.empty?
+          raise UnsupportedBackendError, "Persistence requires Storage SPI 2: #{(missing.keys + missing_methods).join(", ")}"
+        end
+      end
+
+      # @api public
+      def capabilities
+        REQUIRED_CAPABILITIES.transform_values { |value| (value == true) ? false : value }.freeze
+      end
+
+      # Whether this synchronous context is already inside a backend transaction.
+      # Lets higher-level scopes reject claiming ownership of somebody else's commit.
+      # @api public
+      def transaction_open? = !current_view.nil?
+
+      # All declared resources participate in one atomic transaction domain.
+      # Record and stream revisions provide compare-and-swap conflict detection.
+      # This does not
+      # mean cross-process Workflow admission or distributed locking.
+      # Storage failures whose commit outcome is fundamentally unknown remain
+      # database failures; Phronomy does not claim exactly-once semantics.
+      # Explicit nesting uses savepoints. Non-local block exits raise and roll back.
+      # @api public
+      def transaction
+        current_view&.validate!
+        storage_transaction do |context|
+          scope = Scope.new
+          bound = View.new(self, scope: scope, context: context)
+          views = stack
+          views.push(bound)
+          completed = false
+          begin
+            result = yield bound
+            scope.check!
+            completed = true
+            result
+          ensure
+            scope.close!
+            views.pop
+            Thread.current.thread_variable_get(:phronomy_storage_scopes)&.delete(self) if views.empty?
+            if !completed && $!.nil?
+              raise TransactionError, "transaction block must complete normally; non-local exit rolled back"
+            end
+          end
+        end
+      end
+
+      # @api private
+      def current_view
+        Thread.current.thread_variable_get(:phronomy_storage_scopes)&.dig(self)&.last.tap { |bound| bound&.validate! }
+      end
+
+      # @api private
+      def execute(context, operation, resource, **arguments)
+        send(operation, context, resource, **arguments)
+      end
+
+      private
+
+      def stack
+        scopes = Thread.current.thread_variable_get(:phronomy_storage_scopes)
+        unless scopes
+          scopes = {}
+          Thread.current.thread_variable_set(:phronomy_storage_scopes, scopes)
+        end
+        scopes[self] ||= []
+      end
+
+      def storage_transaction
+        raise UnsupportedBackendError, "backend must implement an atomic storage transaction"
+      end
+    end
+  end
+end

data/lib/phronomy/storage/backends/in_memory.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Phronomy
+  module Storage
+    module Backends
+      # One Monitor and snapshot cover every declared resource and nested scope.
+      # @api public
+      class InMemory < Backend
+        # @api public
+        def initialize(resources: [])
+          super
+          @monitor = Monitor.new
+          @state = resources.to_h { |resource| [resource.id, {}] }
+        end
+
+        # @api public
+        def capabilities = REQUIRED_CAPABILITIES
+
+        private
+
+        def storage_transaction
+          @monitor.synchronize do
+            snapshot = Marshal.load(Marshal.dump(@state))
+            completed = false
+            begin
+              result = yield @state
+              completed = true
+              result
+            ensure
+              @state.replace(snapshot) unless completed
+            end
+          end
+        end
+
+        def bucket(state, resource) = state.fetch(resource.id)
+
+        def read_record(state, resource, key:)
+          value = bucket(state, resource)[key]
+          value && Entry::Record.new(**value.to_h)
+        end
+
+        def lock_guard(state, resource, key:)
+          raise NotFoundError, "guard record not found: #{resource.id}/#{key}" unless bucket(state, resource).key?(key)
+          true
+        end
+
+        def guard_record(state, resource, key:, attributes: {}, creating: false)
+          guard = resource.guard
+          return unless guard
+          anchor = resources.fetch(guard.fetch(:resource))
+          return if creating && anchor.equal?(resource) && guard[:via] == :key
+          guard_key = [:key, :stream].include?(guard[:via]) ? key : attributes.fetch(guard[:via])
+          lock_guard(state, anchor, key: guard_key)
+        end
+
+        def check_unique(state, resource, entry)
+          resource.unique.each do |constraint|
+            next if constraint[:fields].any? { |key| entry.attributes[key].nil? }
+            next unless constraint.fetch(:where).all? { |key, value| entry.attributes[key] == value }
+            conflict = bucket(state, resource).values.any? do |other|
+              other.key != entry.key && constraint[:where].all? { |k, val| other.attributes[k] == val } && constraint[:fields].all? { |k| other.attributes[k] == entry.attributes[k] }
+            end
+            raise UniqueConstraintError.new(resource: resource, constraint: constraint[:name]) if conflict
+          end
+        end
+
+        def insert_record(state, resource, entry:)
+          raise ConflictError, "duplicate record identity" if bucket(state, resource).key?(entry.key)
+          guard_record(state, resource, key: entry.key, attributes: entry.attributes, creating: true)
+          check_unique(state, resource, entry)
+          bucket(state, resource)[entry.key] = entry
+          Entry::Record.new(**entry.to_h)
+        end
+
+        def replace_record(state, resource, entry:, expected_revision:, expected_attributes:)
+          current = bucket(state, resource)[entry.key] || raise(NotFoundError, "record not found: #{entry.key}")
+          guard_record(state, resource, key: entry.key, attributes: current.attributes)
+          raise ConflictError, "record revision conflict" unless current.revision == expected_revision
+          unless expected_attributes.all? { |key, value| current.attributes[key] == value } && resource.immutable_attributes.all? { |key| current.attributes[key] == entry.attributes[key] }
+            raise ConflictError, "record attribute precondition failed"
+          end
+          check_unique(state, resource, entry)
+          bucket(state, resource)[entry.key] = entry
+          Entry::Record.new(**entry.to_h)
+        end
+
+        def delete_record(state, resource, key:, expected_revision:)
+          current = bucket(state, resource)[key]
+          if !expected_revision.equal?(Records::UNCHECKED) && (!current || current.revision != expected_revision)
+            raise ConflictError, "record deletion revision conflict"
+          end
+          return nil unless current
+          guard_record(state, resource, key: key, attributes: current.attributes)
+          bucket(state, resource).delete(key)
+          nil
+        end
+
+        def scan_records(state, resource, equals:, after:, limit:)
+          entries = bucket(state, resource).values.select { |entry| (!after || entry.key.b > after.b) && equals.all? { |key, value| entry.attributes[key] == value } }.sort_by { |entry| entry.key.b }
+          entries = entries.first(limit) if limit
+          entries.map { |entry| Entry::Record.new(**entry.to_h) }.freeze
+        end
+
+        def delete_matching_records(state, resource, equals:)
+          if resource.guard && ![:key, :stream].include?(resource.guard[:via])
+            raise ArgumentError, "deletion must constrain its guard attribute" unless equals.key?(resource.guard[:via])
+            guard_record(state, resource, key: "unused", attributes: equals)
+          end
+          scan_records(state, resource, equals: equals, after: nil, limit: nil).each do |entry|
+            delete_record(state, resource, key: entry.key, expected_revision: Records::UNCHECKED)
+          end
+          nil
+        end
+
+        def append_stream(state, resource, stream:, expected_head:, entries:)
+          guard_record(state, resource, key: stream)
+          stored = bucket(state, resource).fetch(stream, [])
+          raise ConflictError, "stream head conflict" unless stored.length == expected_head
+          raise ConflictError, "duplicate stream entry identity" unless (stored.map(&:id) & entries.map(&:id)).empty?
+          appended = entries.each_with_index.map { |entry, index| Entry::Stream.new(position: expected_head + index + 1, id: entry.id, record: entry.record) }
+          bucket(state, resource)[stream] = stored + appended unless appended.empty?
+          appended.map { |entry| Entry::Stream.new(**entry.to_h) }.freeze
+        end
+
+        def read_stream(state, resource, stream:, after:, limit:)
+          selected = bucket(state, resource).fetch(stream, []).select { |entry| entry.position > after }
+          selected = selected.first(limit) if limit
+          selected.map { |entry| Entry::Stream.new(**entry.to_h) }.freeze
+        end
+
+        def stream_head(state, resource, stream:) = bucket(state, resource).fetch(stream, []).length
+
+        def delete_stream(state, resource, stream:)
+          guard_record(state, resource, key: stream)
+          bucket(state, resource).delete(stream)
+          nil
+        end
+
+        def put_blob(state, resource, blob:)
+          stored = bucket(state, resource)[blob.key]
+          raise BlobConflictError, "blob bytes are immutable" if stored && stored.bytes != blob.bytes
+          stored ||= bucket(state, resource)[blob.key] = blob
+          Entry::Blob.new(**stored.to_h)
+        end
+
+        def fetch_blob(state, resource, key:)
+          stored = bucket(state, resource)[key] || raise(NotFoundError, "blob not found: #{key}")
+          Entry::Blob.new(**stored.to_h)
+        end
+
+        def blob_exists(state, resource, key:) = bucket(state, resource).key?(key)
+      end
+    end
+  end
+end

data/lib/phronomy/storage/blob_conflict_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A neutral storage contract failure.
+    # @api public
+    class BlobConflictError < ConflictError
+    end
+  end
+end

data/lib/phronomy/storage/blobs.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Immutable byte values sharing the same transaction domain as other resources.
+    # @api public
+    class Blobs
+      attr_reader :resource
+      def initialize(view, resource) = (@view, @resource = view, resource)
+
+      # @api public
+      def put_if_absent(key:, bytes:, attributes:)
+        @view.validate!
+        blob = Entry::Blob.new(key: key, bytes: bytes, attributes: resource.validate_attributes(attributes))
+        @view.perform(:put_blob, resource, blob: blob)
+      end
+
+      # @api public
+      def fetch(key)
+        @view.validate!
+        @view.perform(:fetch_blob, resource, key: Validation.key(key))
+      end
+
+      # @api public
+      def exist?(key)
+        @view.validate!
+        @view.perform(:blob_exists, resource, key: Validation.key(key))
+      end
+    end
+  end
+end

data/lib/phronomy/storage/condition.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A deliberately closed set of conditions; no payload predicates or callbacks.
+    # @api public
+    module Condition
+      RevisionIs = Data.define(:resource, :key, :expected) do
+        def initialize(resource:, key:, expected:)
+          super(resource: Resource.normalize_reference(resource), key: Validation.key(key), expected: Validation.revision(expected))
+        end
+      end
+      StreamHeadIs = Data.define(:resource, :stream, :expected) do
+        def initialize(resource:, stream:, expected:)
+          super(resource: Resource.normalize_reference(resource), stream: Validation.key(stream), expected: Validation.revision(expected))
+        end
+      end
+      NoRows = Data.define(:resource, :index, :equals) do
+        def initialize(resource:, index:, equals:)
+          super(resource: Resource.normalize_reference(resource), index: index, equals: Validation.immutable(equals))
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/storage/condition_failed_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A neutral storage contract failure.
+    # @api public
+    class ConditionFailedError < ConflictError
+      attr_reader :condition
+      # @api public
+      def initialize(condition)
+        @condition = condition
+        super("storage condition failed: #{condition.class.name}")
+      end
+    end
+  end
+end

data/lib/phronomy/storage/conflict_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # A storage identity, revision, or position precondition failed.
+    # @api public
+    class ConflictError < Phronomy::Error; end
+  end
+end