farce 0 → 0.1.0

data/lib/farce/local/sorted_set.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A scoped set maintained in ascending order.
+    class SortedSet < Farce::Abstract::SortedSet
+      include Shareable::Delegated
+
+      class MutableTreeMap < Farce::Local::TreeMap # :nodoc:
+        BackingState = Data.define(:map, :key_locks)
+        private_constant :BackingState
+
+        private
+
+        def prepare_key(key) = key
+
+        def new_copied_scoped_value(map)
+          BackingState.new(map, Internal::MutableOrderedKeyLockMap.new)
+        end
+
+        def new_scoped_value(entries = nil, **)
+          unless Internal::KeyNormalizer.canonical_entries?(entries)
+            return BackingState.new(
+              Internal::MutableTreeMap.new(entries, **),
+              Internal::MutableOrderedKeyLockMap.new,
+            )
+          end
+
+          map = Internal::MutableTreeMap.new(nil, **)
+          entries.each { map[_1] = _2 }
+          BackingState.new(map, Internal::MutableOrderedKeyLockMap.new)
+        end
+      end
+      private_constant :MutableTreeMap
+
+      # The scope with independent contents.
+      # @return [Symbol] The configured scope name.
+      def scope = map_backend.scope
+
+      private
+
+      def new_map(entries = nil, compare_keys_by_identity: false, scope: :ractor, **)
+        raise ArgumentError, "sorted sets do not support identity comparison" if compare_keys_by_identity
+        MutableTreeMap.new(entries, scope:)
+      end
+    end
+  end
+end

data/lib/farce/local/timer_queue.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable timer queue with independent mutable storage in each scope.
+    class TimerQueue < Abstract::TimerQueue
+      include Shareable::Unfreezable
+      include Scoped
+
+      # @overload initialize(capacity: nil, track_age: false, scope: :ractor)
+      #   @!macro scopes
+      #   @param capacity [Integer, nil] the maximum number of values, or nil for an unbounded queue
+      #   @param track_age [Boolean] whether to track enqueue age and queue generations
+      #   @param scope [Symbol] the scope of the queue
+      #   @param fiber_wait [:auto, :io, :block] how scheduled fibers wait on CRuby
+      #   @return [TimerQueue]
+      def initialize(capacity: nil, track_age: false, scope: :ractor, fiber_wait: :auto)
+        super
+      end
+
+      # @return [Symbol] always returns `:local`
+      def mode = :local
+
+      # @api private
+      def fiber_wait = internal_signal.fiber_wait
+
+      private
+
+      def eager_scoped_value? = false
+      def internal_queue      = scoped_value.first
+      def internal_signal     = scoped_value.last
+
+      def new_scoped_value(capacity: nil, fiber_wait: :auto, track_age: false)
+        signal = Internal::UnsharedSignal.for(fiber_wait)
+        [Internal::UnsharedPriorityQueue.new(capacity:, signal:, track_age:), signal]
+      end
+    end
+  end
+end

data/lib/farce/local/tree_map.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable tree map with independent mutable storage in each scope.
+    #
+    # @!method initialize(entries = nil, scope: :ractor)
+    #   @!macro scopes
+    #   @param entries [Hash, Farce::Abstract::Map, #each, #to_hash, nil] the entries to store initially
+    #   @param scope [Symbol] the scope of the tree map
+    #   @return [TreeMap]
+    class TreeMap < Abstract::TreeMap
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      State = Data.define(:map, :key_locks)
+      private_constant :State
+
+      protected
+
+      def internal_map = scoped_value.map
+      def transaction_key_locks = scoped_value.key_locks
+
+      private
+
+      def freeze_scoped_value(state) = state.map.freeze
+
+      def new_copied_scoped_value(map)
+        State.new(map, Internal::OrderedKeyLockMap.new)
+      end
+
+      def with_key_lock(key, &) = scoped_value.key_locks.synchronize(key, &)
+
+      def new_scoped_value(entries = nil, **)
+        unless Internal::KeyNormalizer.canonical_entries?(entries)
+          return State.new(Internal::TreeMap.new(entries, **), Internal::OrderedKeyLockMap.new)
+        end
+
+        map = Internal::TreeMap.new(nil, **)
+        entries.each { map[_1] = _2 }
+        State.new(map, Internal::OrderedKeyLockMap.new)
+      end
+    end
+  end
+end

data/lib/farce/local/vector.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable vector with independent mutable storage in each scope.
+    #
+    # @!method initialize(source = nil, compare_by_identity: false, scope: :ractor)
+    #   @!macro scopes
+    #   @param source [Array, nil] the initial values
+    #   @param compare_by_identity [Boolean] whether values are compared by identity
+    #   @param scope [Symbol] the scope of the vector
+    #   @return [Vector]
+    class Vector < Abstract::Vector
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      protected
+
+      def internal_vector = scoped_value
+
+      def build_derived_vector(values)
+        self.class.new(values, compare_by_identity: compare_by_identity?, scope:)
+      end
+
+      private def new_scoped_value(...) = Internal::UnsharedVector.new(...)
+    end
+  end
+end

data/lib/farce/local/weak_atom.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable weak atom with independent mutable storage in each scope.
+    #
+    # @!method initialize(value = nil, compare_by_identity: false, scope: :ractor)
+    #   @!macro scopes
+    #   @param value [BasicObject, nil] the initial value
+    #   @param compare_by_identity [Boolean] whether comparisons use object identity instead of equality
+    #   @param scope [Symbol] the scope of the weak atomic reference
+    #   @return [WeakAtom]
+    class WeakAtom < Abstract::WeakAtom
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      protected def internal_atom = scoped_value
+      private def new_scoped_value(...) = Internal::UnsharedWeakAtom.new(...)
+    end
+  end
+end

data/lib/farce/local/weak_key_map.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable weak key map with independent mutable storage in each scope.
+    #
+    # @!method initialize(initial_mapping = nil, scope: :ractor, **options)
+    #   @!macro scopes
+    #   @param initial_mapping [Hash, Farce::Abstract::Map, #each, nil] the entries to store initially
+    #   @param scope [Symbol] the scope of the weak key map
+    #   @option options [Boolean] compare_by_identity (false) whether keys and values are compared by identity
+    #   @option options [Boolean] compare_keys_by_identity (compare_by_identity) whether keys are compared by identity
+    #   @option options [Boolean] compare_values_by_identity (compare_by_identity)
+    #     whether values are compared by identity
+    #   @return [WeakKeyMap]
+    class WeakKeyMap < Abstract::WeakKeyMap
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      protected
+
+      def internal_map = scoped_value
+
+      private
+
+      def new_scoped_value(entries = nil, **)
+        unless @key_normalizer || Internal::KeyNormalizer.canonical_entries?(entries)
+          return Internal::UnsharedWeakKeyMap.new(entries, **)
+        end
+
+        map = Internal::UnsharedWeakKeyMap.new(nil, **)
+        entries&.each { map[_1] = _2 }
+        Internal::KeyNormalizer.wrap_concurrent(map, @key_normalizer)
+      end
+    end
+  end
+end

data/lib/farce/local/weak_map.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable weak map with independent mutable storage in each scope.
+    #
+    # @!method initialize(initial_mapping = nil, scope: :ractor, **options)
+    #   @!macro scopes
+    #   @param initial_mapping [Hash, Farce::Abstract::Map, #each, nil] the entries to store initially
+    #   @param scope [Symbol] the scope of the weak map
+    #   @option options [Boolean] compare_by_identity (false) whether keys and values are compared by identity
+    #   @option options [Boolean] compare_keys_by_identity (compare_by_identity) whether keys are compared by identity
+    #   @option options [Boolean] compare_values_by_identity (compare_by_identity)
+    #     whether values are compared by identity
+    #   @return [WeakMap]
+    class WeakMap < Abstract::WeakMap
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      protected
+
+      def internal_map = scoped_value
+
+      private
+
+      def new_scoped_value(entries = nil, **)
+        unless @key_normalizer || Internal::KeyNormalizer.canonical_entries?(entries)
+          return Internal::UnsharedWeakMap.new(entries, **)
+        end
+
+        map = Internal::UnsharedWeakMap.new(nil, **)
+        entries&.each { map[_1] = _2 }
+        Internal::KeyNormalizer.wrap_concurrent(map, @key_normalizer)
+      end
+    end
+  end
+end

data/lib/farce/local/weak_set.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable weak set with independent mutable contents in each scope.
+    class WeakSet < Farce::Abstract::WeakSet
+      include Shareable::Delegated
+
+      # The scope with independent contents.
+      # @return [Symbol] The configured scope name.
+      def scope = map_backend.scope
+
+      private def new_map(...) = Farce::Local::WeakMap.new(...)
+    end
+  end
+end

data/lib/farce/local/weak_value_map.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable weak value map with independent mutable storage in each scope.
+    #
+    # @!method initialize(initial_mapping = nil, scope: :ractor, **options)
+    #   @!macro scopes
+    #   @param initial_mapping [Hash, Farce::Abstract::Map, #each, nil] the entries to store initially
+    #   @param scope [Symbol] the scope of the weak value map
+    #   @option options [Boolean] compare_by_identity (false) whether keys and values are compared by identity
+    #   @option options [Boolean] compare_keys_by_identity (compare_by_identity) whether keys are compared by identity
+    #   @option options [Boolean] compare_values_by_identity (compare_by_identity)
+    #     whether values are compared by identity
+    #   @return [WeakValueMap]
+    class WeakValueMap < Abstract::WeakValueMap
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      protected
+
+      def internal_map = scoped_value
+
+      private
+
+      def new_scoped_value(entries = nil, **)
+        unless @key_normalizer || Internal::KeyNormalizer.canonical_entries?(entries)
+          return Internal::UnsharedWeakValueMap.new(entries, **)
+        end
+
+        map = Internal::UnsharedWeakValueMap.new(nil, **)
+        entries&.each { map[_1] = _2 }
+        Internal::KeyNormalizer.wrap_concurrent(map, @key_normalizer)
+      end
+    end
+  end
+end

data/lib/farce/local.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # Shareable containers whose mutable contents belong to the current scope.
+  # Scopes may be :ractor, :thread_group, :thread, :fiber_storage, or :fiber.
+  # Initial contents are copied between Ractors. Within a Ractor, each scope has
+  # its own container, but objects supplied as initial contents may be shared.
+  module Local
+    include Internal::Autoloads
+
+    # @overload enfarce(object, freeze: nil, scope: :ractor)
+    #   Converts vanilla Ruby objects into their {Farce::Local} equivalents.
+    #
+    #   @!macro scopes
+    #
+    #   @example
+    #     Farce::Local.enfarce({ foo: ["bar"] })
+    #     # =>  #<Farce::Local::Map {foo: #<Farce::Local::Vector ["bar"]>}>
+    #
+    #
+    #   @yield [object] Optional block, called with any object that doesn't have a specific conversion defined.
+    #   @yieldparam object [BasicObject] the object to convert
+    #   @yieldreturn [BasicObject] the converted object
+    #   @param object [BasicObject] The root object to convert
+    #   @param freeze [Boolean, nil]
+    #     Whether to freeze the converted objects.
+    #     If set to `nil` (default), the freezing behavior will depend on the original object's frozen state.
+    #   @param scope [Symbol] The scope for the local container, e.g., `:ractor`.
+    #   @return [BasicObject] the converted object
+    #   @see Farce.enfarce
+    def self.enfarce(object, **, &) = Internal::Converter.new(self, **, &).convert(object)
+  end
+end

data/lib/farce/lock.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @note
+  #   On JRuby and TruffleRuby, this will be a subclass of Mutex. On CRuby, it will be a custom implementation,
+  #   as Mutex instances are not Ractor-shareable.
+  #
+  # A Ractor-shareable mutual-exclusion lock with the same interface as Ruby's Mutex.
+  #
+  # Lock ownership belongs to the current Fiber. Attempting to lock the same lock recursively raises
+  # ThreadError. Waiting for a lock cooperates with an installed Fiber scheduler.
+  #
+  # @!method lock
+  #   Acquire the lock, waiting until it is available.
+  #   @return [self]
+  #   @raise [ThreadError] if the current Fiber already owns the lock
+  #
+  # @!method locked?
+  #   @return [Boolean] whether any Fiber owns the lock
+  #
+  # @!method owned?
+  #   @return [Boolean] whether the current Fiber owns the lock
+  #
+  # @!method sleep(timeout = nil)
+  #   Release the lock while sleeping, then reacquire it before returning.
+  #   @param timeout [Numeric, nil] the maximum number of seconds to sleep, or nil to sleep indefinitely
+  #   @return [nil]
+  #   @raise [ThreadError] if the current Fiber does not own the lock
+  #
+  # @!method synchronize
+  #   Acquire the lock for the duration of the block.
+  #   @yield the block to run while holding the lock
+  #   @return [Object] the block result
+  #   @raise [ThreadError] if no block is given or the current Fiber already owns the lock
+  #
+  # @!method try_lock
+  #   Attempt to acquire the lock without waiting.
+  #   @return [Boolean] whether the lock was acquired
+  #
+  # @!method unlock
+  #   Release the lock.
+  #   @return [self]
+  #   @raise [ThreadError] if the current Fiber does not own the lock
+  class Lock < Internal::Lock
+    include Internal::MarshalSupport::Reject
+    include Internal::Copyable
+    include Shareable::Native
+    include Shareable::Unfreezable
+
+    private def instance_variables_to_inspect = Internal::EMPTY_ARRAY
+  end
+end

data/lib/farce/lru_map.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable bounded map that evicts the least recently used entry.
+  # Transfer modes apply to values. Equality-mode mutable string keys become immutable.
+  # Individual reads and writes update recency. Iteration and key observation do not.
+  #
+  # @example Keeping copied values in a small cache
+  #   cache = Farce::LRUMap.new(max_size: 2, mode: :copy)
+  #
+  #   cache[:first]  = [1]
+  #   cache[:second] = [2]
+  #   cache[:first] # makes sure :first was accessed more recently than :second
+  #   cache[:third]  = [3]
+  #
+  #   cache.key?(:second) # => false
+  class LRUMap < Farce::Abstract::LRUMap
+    include Shareable::Delegated
+
+    # @!macro modes
+    # @param entries [Hash, Array<Array(BasicObject, BasicObject)>, Abstract::Map, #each, nil]
+    #   Optional initial entries. Entries are stored sequentially and may be evicted.
+    # @param mode [Symbol] The default value transfer mode.
+    def initialize(entries = nil, mode: :copy, **)
+      @manager = marshal_mode_manager(mode)
+      super(entries, **)
+    end
+
+    # The default transfer mode for values.
+    # @return [Symbol]
+    def mode = @manager.mode
+
+    # Keys must be shareable, except equality-mode strings that can be snapshotted.
+    # @return [true]
+    def shareable_keys? = true
+
+    # Values are stored in Ractor-shareable representations.
+    # @return [true]
+    def shareable_values? = true
+
+    protected
+
+    def unwrap_value(value) = @manager.unwrap(value)
+
+    def wrap_value(value)
+      check_frozen!
+      @manager.wrap(value)
+    end
+
+    private
+
+    def each_for_inspect(&)             = internal_map.each(&)
+    def inspect_value(inspector, value) = super(inspector, value, @manager)
+    def new_bounded_map(...)            = Internal::StrictLRUMap.new(...)
+    def freeze_backend                  = internal_map
+
+    def new_key_locks(compare_keys_by_identity:)
+      Internal::KeyLockMap.new(registry_class: Farce::Strict::Map, compare_keys_by_identity:)
+    end
+  end
+end

data/lib/farce/map.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A concurrent map with direct shareable keys and strongly retained values.
+  # Transfer modes apply only to values. String keys use their frozen unary-minus form,
+  # except when comparing keys by identity. Other keys must already be shareable.
+  # Values stored through this map's mode manager are automatically unwrapped.
+  # Updates on different keys can run concurrently.
+  #
+  # Clearing the map invalidates unfinished updates so they cannot restore removed entries.
+  #
+  # `dup` and `clone` copy entries into independent storage while sharing stored values.
+  # Move-mode envelopes keep their ownership across copies. `dup` and ordinary `clone`
+  # remain Ractor-shareable.
+  #
+  # @example Atomically updating a value
+  #   map = Farce::Map.new({ count: 0 })
+  #   map.update(:count) { |count| count + 1 } # => 1
+  #
+  # @example Automatically making values shareable
+  #   map = Farce::Map.new(mode: :make_shareable)
+  #   map[:jobs] = []
+  #   map.update(:jobs) { |items| items + [:job] } # => [:job]
+  #   map[:jobs] # => [:job]
+  #   Ractor.shareable?(map[:jobs]) # => true
+  #
+  # @!parse
+  #   class Map
+  #     # @!macro map_initialization
+  #     # @!macro modes
+  #     # @param mode [Symbol] The default transfer mode for values. Defaults to `:copy`.
+  #     # @return [Map]
+  #     def initialize(
+  #       initial_mapping = nil,
+  #       mode: :copy,
+  #       normalize_keys: nil,
+  #       compare_by_identity: false,
+  #       compare_keys_by_identity: compare_by_identity,
+  #       compare_values_by_identity: compare_by_identity
+  #     )
+  #     end
+  #   end
+  class Map < Abstract::ConcurrentMap
+    include Internal::MapValueModes
+    include Shareable::Delegated
+
+    private
+
+    def new_map(**)    = Internal::StrictMap.new(**)
+    def freeze_backend = @map
+
+    Internal.prepare_map_access(self, :modes)
+  end
+
+  Internal::KeyNormalizer.prepare_concurrent_class(Internal::StrictMap)
+end

data/lib/farce/mode_manager.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A mode manager encapsulates logic for dealing with Ruby objects that aren't Ractor-shareable.
+  # It is a perfect companion piece for APIs that require Ractor-shareable objects.
+  #
+  # For instance, [Ratomic::Queue](https://mperham.github.io/ratomic/Ratomic/Queue.html) expects Ractor-shareable
+  # objects without checking for them. Creating a thin wrapper with a mode manager allows you to use it safely and with
+  # non-shareable objects.
+  #
+  # ```ruby
+  # require "ratomic"
+  # require "farce"
+  #
+  # class MyQueue
+  #   include Farce::Shareable
+  #
+  #   def initialize(capacity: 1024, mode: :copy)
+  #     @queue   = Ratomic::Queue.new(capacity)
+  #     @manager = Farce::ModeManager.new(mode:)
+  #   end
+  #
+  #   def pop = @manager.unwrap(@queue.pop)
+  #
+  #   def push(value, mode: nil)
+  #     @queue.push(@manager.wrap(value, mode:))
+  #     self
+  #   end
+  # end
+  #
+  # queue = MyQueue.new(capacity: 100, mode: :move)
+  #
+  # # consume the queue on a different Ractor
+  # Ractor.new(queue) { |q| p Ractor.shareable?(q.pop) }
+  #
+  # object = Object.new
+  # q.push(object)
+  #
+  # # push moved the object into the queue, so it is no longer accessible on the current Ractor
+  # Ractor::MovedObject === object # => true
+  # ```
+  #
+  # It is recommended to use a different mode manager for each instance of a queue, port, or whatever else you're
+  # wrapping, as {#wrap} may create an {Envelope} and {#unwrap} will only unwrap envelopes created by the same mode
+  # manager. This way users can still safely send envelopes they created between Ractors without them getting
+  # unexpectedly claimed.
+  #
+  # @!macro modes
+  class ModeManager
+    include Internal::Copyable
+    include Shareable::Immutable
+
+    # @return [Symbol] The default mode to use when wrapping values.
+    attr_reader :mode
+
+    # @!macro modes
+    # @param mode [Symbol] The default mode to use when wrapping values. Must be one of the valid modes.
+    # @param register [Proxy::Register, nil] The register to use for generating Farce::Proxy instances.
+    def initialize(mode: :copy, register: nil)
+      raise ArgumentError, "invalid mode: #{mode.inspect}" unless Farce::MODES.include?(mode)
+      @mode     = mode
+      @register = register
+      super()
+    end
+
+    # @api private
+    def marshal_dump
+      raise TypeError, "proxy registers cannot be marshaled" if @register
+      [1, mode]
+    end
+
+    # @api private
+    def marshal_load(data)
+      mode, = Internal::MarshalSupport.payload(data, 1)
+      initialize(mode:)
+    end
+
+    # Wraps a value in an envelope if it is not Ractor-shareable.
+    #
+    # @!macro modes
+    # @param value [BasicObject] The value to wrap.
+    # @param mode [Symbol, nil] The mode to use when wrapping the value. If `nil`, the default mode will be used.
+    # @return [BasicObject, Envelope]
+    #   The prepared value, or a managed envelope containing it.
+    def wrap(value, mode: nil)
+      return value if Ractor.shareable?(value)
+
+      case mode || self.mode
+      when :copy           then Envelope::Copy.new(value, self)
+      when :dedup          then Ractor.make_shareable(Farce.dedup(value))
+      when :local          then Envelope::Local.new(value, self)
+      when :make_shareable then Ractor.make_shareable(value)
+      when :move           then Envelope::Move.new(value, self)
+      when :mutable        then Mutable.new(value)
+      when :raise          then raise Ractor::IsolationError, "value is not Ractor-shareable: #{value.inspect}"
+      when :shareable_copy then Ractor.make_shareable(value, copy: true)
+      when :proxy          then Proxy.new(value, register: @register)
+      else raise ArgumentError, "invalid mode: #{mode.inspect}"
+      end
+    end
+
+    # Unwraps any envelope created by this mode manager, returning the value inside.
+    # Other options, including other envelopes, will be returned as-is.
+    # @param value [BasicObject, Envelope] The value to unwrap.
+    # @return [BasicObject]
+    #   The value inside the envelope if it was created by this mode manager, or the value itself if it was not.
+    def unwrap(value)
+      return value unless managed_envelope?(value)
+      value.value
+    end
+
+    # Compares two values managed by this instance. Compatible envelopes can be
+    # compared without claiming or opening them.
+    # @param left [BasicObject, Envelope] The stored value.
+    # @param right [BasicObject, Envelope] The comparison value.
+    # @param identity [Boolean] Whether to compare by identity instead of equality.
+    # @return [Boolean] Whether the values match.
+    def same_value?(left, right, identity: false)
+      left_managed  = managed_envelope?(left)
+      right_managed = managed_envelope?(right)
+
+      if left_managed && right_managed
+        return false if identity && Envelope::Move === left && Envelope::Local === right && !left.owned?
+        return left.same_value?(right, identity:)
+      end
+
+      return false if identity && left_managed
+      return left.same_value?(right) if left_managed
+
+      left  = unwrap(left)
+      right = unwrap(right)
+      return BasicObject.instance_method(:equal?).bind_call(left, right) if identity
+
+      left == right
+    end
+
+    # @return [Boolean] Whether the value is an envelope managed by this mode manager.
+    def managed_envelope?(value) = Envelope === value && value.auto_unwrap.equal?(self)
+  end
+end