llmemory 0.2.10 → 0.3.0

data/lib/llmemory/zero_mem/storages/memory.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require_relative "../storage"
+
+module Llmemory
+  module ZeroMem
+    module Storages
+      class Memory
+        include Storage
+
+        def initialize
+          @traces = {}
+          @idempotency = {}
+          @sequences = Hash.new(0)
+          @state_links = []
+          @watermarks = {}
+          @units = {}
+          @open_episodes = {}
+          @entities = {}
+          @mentions = []
+          @entity_traces = Hash.new { |h, k| h[k] = [] }
+          @trace_entity_keys = Hash.new { |h, k| h[k] = [] }
+          @adjacency = {}
+          @turn_embeddings = {}
+        end
+
+        def write_trace(trace)
+          t = trace.is_a?(Trace) ? trace : Trace.new(**trace)
+          key = idempotency_key(t.user_id, t.idempotency_key)
+          if key && @idempotency[key]
+            return @idempotency[key]
+          end
+          if t.idempotency_key && (existing = find_by_idempotency_key(t.user_id, t.idempotency_key))
+            return existing.id
+          end
+
+          @traces[t.id] = t
+          @idempotency[key] = t.id if key
+          @sequences[[t.user_id, t.session_id]] = t.sequence if t.sequence > @sequences[[t.user_id, t.session_id]]
+          t.id
+        end
+
+        def get_trace(user_id, trace_id)
+          t = @traces[trace_id.to_s]
+          return nil unless t
+          return nil unless t.user_id == user_id.to_s
+
+          t
+        end
+
+        def find_by_idempotency_key(user_id, idempotency_key)
+          id = @idempotency[idempotency_key(user_id, idempotency_key)]
+          id ? get_trace(user_id, id) : nil
+        end
+
+        def next_sequence(user_id, session_id)
+          @sequences[[user_id.to_s, session_id.to_s]] + 1
+        end
+
+        def list_traces(user_id, session_id: nil, include_archived: false, limit: nil, offset: nil)
+          uid = user_id.to_s
+          list = @traces.values.select do |t|
+            next false unless t.user_id == uid
+            next false if session_id && t.session_id != session_id.to_s
+            next false if !include_archived && !t.active?
+
+            true
+          end
+          list.sort_by! { |t| [t.session_id, t.sequence, t.ingested_at.to_f] }
+          list = list.drop(offset.to_i) if offset
+          list = list.first(limit.to_i) if limit && limit.to_i.positive?
+          list
+        end
+
+        def archive_trace(user_id, trace_id, archived_at: Time.now)
+          t = get_trace(user_id, trace_id)
+          return false unless t
+
+          @traces[t.id] = t.with(archived_at: archived_at)
+          cascade_archive_derivatives(user_id, t.id)
+          true
+        end
+
+        def write_state_link(link)
+          @state_links << link
+          link.trace_id
+        end
+
+        def close_open_state_links(user_id, state_key, valid_to:, except_trace_id: nil)
+          uid = user_id.to_s
+          sk = state_key.to_s
+          closed = 0
+          @state_links.each_with_index do |link, idx|
+            next unless link.user_id == uid && link.state_key == sk
+            next unless link.valid_to.nil?
+            next if except_trace_id && link.trace_id == except_trace_id.to_s
+
+            @state_links[idx] = TraceStateLink.new(
+              user_id: link.user_id,
+              state_key: link.state_key,
+              trace_id: link.trace_id,
+              valid_from: link.valid_from,
+              valid_to: valid_to,
+              supersedes_trace_id: link.supersedes_trace_id,
+              source: link.source,
+              created_at: link.created_at
+            )
+            closed += 1
+          end
+          closed
+        end
+
+        def state_links_for(user_id, state_key)
+          @state_links.select { |l| l.user_id == user_id.to_s && l.state_key == state_key.to_s }
+                      .sort_by { |l| [l.valid_from.to_f, l.created_at.to_f] }
+        end
+
+        def current_state_trace_id(user_id, state_key, as_of: Time.now)
+          state_links_for(user_id, state_key).reverse.find { |l| l.active_at?(as_of) }&.trace_id
+        end
+
+        def get_watermark(user_id, session_id)
+          @watermarks[[user_id.to_s, session_id.to_s]] || { last_sequence: 0, index_version: 0 }
+        end
+
+        def set_watermark(user_id, session_id, last_sequence:, index_version:)
+          @watermarks[[user_id.to_s, session_id.to_s]] = {
+            last_sequence: last_sequence.to_i,
+            index_version: index_version.to_i
+          }
+        end
+
+        def write_unit(unit)
+          u = unit.is_a?(TraceUnit) ? unit : TraceUnit.new(**unit)
+          @units[u.id] = u
+          u.id
+        end
+
+        def list_units(user_id, kind: nil, session_id: nil, boundary_id: nil)
+          uid = user_id.to_s
+          @units.values.select do |u|
+            next false unless u.user_id == uid
+            next false if kind && u.kind != kind.to_sym
+            next false if session_id && u.session_id != session_id.to_s
+            next false if boundary_id && u.boundary_id != boundary_id.to_s
+            next false if unit_references_archived_trace?(u)
+
+            true
+          end.sort_by { |u| [u.kind.to_s, u.start_sequence, u.end_sequence] }
+        end
+
+        def get_unit(user_id, unit_id)
+          u = @units[unit_id.to_s]
+          return nil unless u
+          return nil unless u.user_id == user_id.to_s
+
+          u
+        end
+
+        def open_episode(user_id, episode_key)
+          id = @open_episodes[[user_id.to_s, episode_key.to_s]]
+          id ? get_unit(user_id, id) : nil
+        end
+
+        def set_open_episode(user_id, episode_key, unit_id)
+          @open_episodes[[user_id.to_s, episode_key.to_s]] = unit_id.to_s
+        end
+
+        def close_episode(unit_id)
+          @open_episodes.delete_if { |_, v| v == unit_id.to_s }
+        end
+
+        def upsert_entity(entity)
+          ent = entity.is_a?(Entity) ? entity : Entity.new(**entity)
+          key = [ent.user_id, ent.normalized_key]
+          @entities[key] = ent
+          ent.id
+        end
+
+        def write_mention(mention)
+          m = mention.is_a?(EntityMention) ? mention : EntityMention.new(**mention)
+          @mentions << m
+          @entity_traces[[m.user_id, m.normalized_key]] << m.trace_id unless @entity_traces[[m.user_id, m.normalized_key]].include?(m.trace_id)
+          @trace_entity_keys[[m.user_id, m.trace_id]] << m.normalized_key unless @trace_entity_keys[[m.user_id, m.trace_id]].include?(m.normalized_key)
+          m.id
+        end
+
+        def entity_exists?(user_id, normalized_key)
+          @entities.key?([user_id.to_s, normalized_key.to_s])
+        end
+
+        def trace_ids_for_entity_key(user_id, normalized_key)
+          @entity_traces[[user_id.to_s, normalized_key.to_s]].select do |tid|
+            active_trace?(user_id, tid)
+          end
+        end
+
+        def entity_keys_for_trace(user_id, trace_id)
+          @trace_entity_keys[[user_id.to_s, trace_id.to_s]].dup
+        end
+
+        def previous_trace(user_id, session_id, sequence)
+          list_traces(user_id, session_id: session_id).reverse.find { |t| t.sequence < sequence.to_i }
+        end
+
+        def link_adjacent_traces(user_id, prev_trace_id, trace_id)
+          uid = user_id.to_s
+          @adjacency[prev_trace_id.to_s] ||= {}
+          @adjacency[prev_trace_id.to_s][:next] = trace_id.to_s
+          @adjacency[trace_id.to_s] ||= {}
+          @adjacency[trace_id.to_s][:prev] = prev_trace_id.to_s
+        end
+
+        def adjacent_traces(user_id, trace_id)
+          _uid = user_id.to_s
+          adj = @adjacency[trace_id.to_s] || {}
+          [adj[:prev], adj[:next]]
+        end
+
+        def all_entity_keys(user_id)
+          uid = user_id.to_s
+          @entities.select { |(u, _), _| u == uid }.map { |(_, key), _| key }
+        end
+
+        def store_turn_embedding(user_id, trace_id, vector, model:, dimensions:)
+          @turn_embeddings[[user_id.to_s, trace_id.to_s]] = {
+            vector: vector,
+            model: model,
+            dimensions: dimensions
+          }
+        end
+
+        def search_traces_by_tokens(user_id, query, limit: 20)
+          tokens = Llmemory::Tokenizer.tokenize(query)
+          return [] if tokens.empty?
+
+          list = list_traces(user_id)
+          matched = list.select do |t|
+            down = t.content.downcase
+            tokens.all? { |tok| down.include?(tok) }
+          end
+          limit.to_i.positive? ? matched.first(limit.to_i) : matched
+        end
+
+        def reset_state!
+          @traces = {}
+          @idempotency = {}
+          @sequences = Hash.new(0)
+          @state_links = []
+          @watermarks = {}
+          @units = {}
+          @open_episodes = {}
+          @entities = {}
+          @mentions = []
+          @entity_traces = Hash.new { |h, k| h[k] = [] }
+          @trace_entity_keys = Hash.new { |h, k| h[k] = [] }
+          @adjacency = {}
+          @turn_embeddings = {}
+        end
+
+        private
+
+        def cascade_archive_derivatives(user_id, trace_id)
+          uid = user_id.to_s
+          tid = trace_id.to_s
+          @mentions.reject! { |m| m.user_id == uid && m.trace_id == tid }
+          @trace_entity_keys.delete([uid, tid])
+          @entity_traces.each_value { |ids| ids.delete(tid) }
+          @turn_embeddings.delete([uid, tid])
+          @adjacency.delete(tid)
+          @adjacency.each_value do |adj|
+            adj.delete(:prev) if adj[:prev] == tid
+            adj.delete(:next) if adj[:next] == tid
+          end
+        end
+
+        def unit_references_archived_trace?(unit)
+          unit.member_trace_ids.any? { |tid| !active_trace?(unit.user_id, tid) }
+        end
+
+        def active_trace?(user_id, trace_id)
+          t = get_trace(user_id, trace_id)
+          t&.active?
+        end
+
+        def idempotency_key(user_id, key)
+          return nil if key.nil? || key.to_s.empty?
+
+          [user_id.to_s, key.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/storages/postgres.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../storage"
+require_relative "memory"
+require_relative "snapshot_codec"
+require_relative "../../crypto/field_helpers"
+
+module Llmemory
+  module ZeroMem
+    module Storages
+      class PostgresStorage
+        include Storage
+        include Llmemory::Crypto::FieldHelpers
+
+        SNAPSHOT_ID = "default"
+        MUTATORS = Storages::FileStorage::MUTATORS
+
+        def initialize(database_url: nil, cipher: nil)
+          @database_url = database_url || Llmemory.configuration.database_url || ENV["DATABASE_URL"]
+          raise ConfigurationError, "DATABASE_URL required for zero_mem postgres store" if @database_url.to_s.empty?
+
+          require "pg"
+          @conn = PG.connect(@database_url)
+          @cipher = cipher || Llmemory.build_cipher
+          @inner = Memory.new
+          ensure_tables!
+          load!
+        end
+
+        Storage.instance_methods(false).each do |method_name|
+          next if MUTATORS.include?(method_name)
+
+          define_method(method_name) do |*args, **kwargs, &block|
+            @inner.public_send(method_name, *args, **kwargs, &block)
+          end
+        end
+
+        MUTATORS.each do |method_name|
+          define_method(method_name) do |*args, **kwargs, &block|
+            result = @inner.public_send(method_name, *args, **kwargs, &block)
+            save!
+            result
+          end
+        end
+
+        private
+
+        def ensure_tables!
+          @conn.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS llmemory_zero_mem_snapshots (
+              id TEXT PRIMARY KEY,
+              payload TEXT NOT NULL,
+              updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            );
+          SQL
+        end
+
+        def load!
+          result = @conn.exec_params(
+            "SELECT payload FROM llmemory_zero_mem_snapshots WHERE id = $1",
+            [SNAPSHOT_ID]
+          )
+          return if result.ntuples.zero?
+
+          raw = dec(result.first["payload"])
+          data = JSON.parse(raw, symbolize_names: true)
+          SnapshotCodec.load!(@inner, data)
+        end
+
+        def save!
+          payload = enc(JSON.generate(SnapshotCodec.dump(@inner)))
+          @conn.exec_params(
+            <<~SQL,
+              INSERT INTO llmemory_zero_mem_snapshots (id, payload, updated_at)
+              VALUES ($1, $2, NOW())
+              ON CONFLICT (id) DO UPDATE SET payload = EXCLUDED.payload, updated_at = NOW()
+            SQL
+            [SNAPSHOT_ID, payload]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/storages/snapshot_codec.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    module Storages
+      module SnapshotCodec
+        VERSION = 1
+
+        module_function
+
+        def dump(store)
+          {
+            version: VERSION,
+            traces: store.instance_variable_get(:@traces).transform_values(&:to_h),
+            idempotency: encode_tuple_keys(store.instance_variable_get(:@idempotency)),
+            sequences: encode_tuple_keys(store.instance_variable_get(:@sequences)),
+            state_links: store.instance_variable_get(:@state_links).map(&:to_h),
+            watermarks: encode_tuple_keys(store.instance_variable_get(:@watermarks)),
+            units: store.instance_variable_get(:@units).transform_values { |u| unit_to_h(u) },
+            open_episodes: encode_tuple_keys(store.instance_variable_get(:@open_episodes)),
+            entities: encode_tuple_keys(
+              store.instance_variable_get(:@entities).transform_values { |e| entity_to_h(e) }
+            ),
+            mentions: store.instance_variable_get(:@mentions).map { |m| mention_to_h(m) },
+            entity_traces: encode_tuple_keys(store.instance_variable_get(:@entity_traces)),
+            trace_entity_keys: encode_tuple_keys(store.instance_variable_get(:@trace_entity_keys)),
+            adjacency: store.instance_variable_get(:@adjacency),
+            turn_embeddings: encode_tuple_keys(store.instance_variable_get(:@turn_embeddings))
+          }
+        end
+
+        def encode_tuple_keys(hash)
+          hash.each_with_object({}) do |(key, value), acc|
+            encoded = key.is_a?(Array) ? key.join("|") : key.to_s
+            acc[encoded] = value
+          end
+        end
+
+        def decode_tuple_keys(hash, default_factory: nil)
+          out = default_factory ? Hash.new { |h, k| h[k] = default_factory.call } : {}
+          hash.each do |key, value|
+            parts = key.to_s.split("|", 2)
+            out_key = parts.size == 2 ? [parts[0], parts[1]] : key
+            out[out_key] = value
+          end
+          out
+        end
+
+        def load!(store, data)
+          store.send(:reset_state!)
+          data = data.transform_keys(&:to_sym)
+          traces_h = data[:traces]
+          trace_rows = traces_h.is_a?(Hash) ? traces_h.values : Array(traces_h)
+          trace_rows.each do |h|
+            trace = Trace.new(**symbolize_times(h))
+            store.instance_variable_get(:@traces)[trace.id] = trace
+          end
+          store.instance_variable_set(:@idempotency, decode_tuple_keys(data[:idempotency] || {}))
+          sequences = decode_tuple_keys(data[:sequences] || {})
+          sequences.default = 0
+          store.instance_variable_set(:@sequences, sequences)
+          store.instance_variable_set(:@state_links, Array(data[:state_links]).map { |h| TraceStateLink.new(**symbolize_times(h)) })
+          store.instance_variable_set(:@watermarks, decode_tuple_keys(data[:watermarks] || {}))
+          units_h = data[:units]
+          unit_rows = units_h.is_a?(Hash) ? units_h.values : Array(units_h)
+          unit_rows.each do |h|
+            unit = unit_from_h(h)
+            store.instance_variable_get(:@units)[unit.id] = unit
+          end
+          store.instance_variable_set(:@open_episodes, decode_tuple_keys(data[:open_episodes] || {}))
+          decode_tuple_keys(data[:entities] || {}).each_value do |h|
+            ent = entity_from_h(h)
+            store.instance_variable_get(:@entities)[[ent.user_id, ent.normalized_key]] = ent
+          end
+          store.instance_variable_set(:@mentions, Array(data[:mentions]).map { |h| mention_from_h(h) })
+          store.instance_variable_set(
+            :@entity_traces,
+            decode_tuple_keys(data[:entity_traces] || {}, default_factory: -> { [] })
+          )
+          store.instance_variable_get(:@entity_traces).default_proc = proc { |h, k| h[k] = [] }
+          store.instance_variable_set(
+            :@trace_entity_keys,
+            decode_tuple_keys(data[:trace_entity_keys] || {}, default_factory: -> { [] })
+          )
+          store.instance_variable_get(:@trace_entity_keys).default_proc = proc { |h, k| h[k] = [] }
+          store.instance_variable_set(:@adjacency, data[:adjacency] || {})
+          store.instance_variable_set(:@turn_embeddings, decode_tuple_keys(data[:turn_embeddings] || {}))
+          store
+        end
+
+        def unit_to_h(unit)
+          {
+            id: unit.id,
+            user_id: unit.user_id,
+            kind: unit.kind,
+            session_id: unit.session_id,
+            boundary_id: unit.boundary_id,
+            start_sequence: unit.start_sequence,
+            end_sequence: unit.end_sequence,
+            occurred_from: unit.occurred_from.utc.iso8601(6),
+            occurred_to: unit.occurred_to.utc.iso8601(6),
+            member_trace_ids: unit.member_trace_ids,
+            embedding_ref: unit.embedding_ref,
+            index_version: unit.index_version
+          }
+        end
+
+        def unit_from_h(h)
+          h = symbolize_times(h)
+          TraceUnit.new(
+            id: h[:id],
+            user_id: h[:user_id],
+            kind: h[:kind].to_sym,
+            session_id: h[:session_id],
+            boundary_id: h[:boundary_id],
+            start_sequence: h[:start_sequence],
+            end_sequence: h[:end_sequence],
+            occurred_from: h[:occurred_from],
+            occurred_to: h[:occurred_to],
+            member_trace_ids: h[:member_trace_ids] || [],
+            embedding_ref: h[:embedding_ref],
+            index_version: h[:index_version] || 0
+          )
+        end
+
+        def entity_to_h(entity)
+          {
+            id: entity.id,
+            user_id: entity.user_id,
+            normalized_key: entity.normalized_key,
+            display_name: entity.display_name,
+            entity_type: entity.entity_type,
+            ambiguous: entity.ambiguous
+          }
+        end
+
+        def entity_from_h(h)
+          h = h.transform_keys(&:to_sym)
+          Entity.new(
+            id: h[:id],
+            user_id: h[:user_id],
+            normalized_key: h[:normalized_key],
+            display_name: h[:display_name],
+            entity_type: (h[:entity_type] || :entity).to_sym,
+            ambiguous: h[:ambiguous] || false
+          )
+        end
+
+        def mention_to_h(mention)
+          {
+            id: mention.id,
+            user_id: mention.user_id,
+            trace_id: mention.trace_id,
+            entity_id: mention.entity_id,
+            normalized_key: mention.normalized_key,
+            text: mention.text,
+            offset_start: mention.offset_start,
+            offset_end: mention.offset_end
+          }
+        end
+
+        def mention_from_h(h)
+          EntityMention.new(**h.transform_keys(&:to_sym))
+        end
+
+        def symbolize_times(h)
+          out = h.transform_keys(&:to_sym)
+          %i[occurred_at ingested_at archived_at valid_from valid_to created_at occurred_from occurred_to].each do |key|
+            next unless out[key]
+
+            out[key] = Time.parse(out[key].to_s) unless out[key].is_a?(Time)
+          end
+          out[:role] = out[:role].to_sym if out[:role]
+          out[:source] = out[:source].to_sym if out[:source]
+          out
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/storages.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "storages/memory"
+
+module Llmemory
+  module ZeroMem
+    module Storages
+      def self.build(store: nil, cipher: nil)
+        resolved = store || resolve_store
+        case resolved.to_sym
+        when :memory
+          Memory.new
+        when :file
+          require_relative "storages/file"
+          FileStorage.new(cipher: cipher)
+        when :postgres
+          require_relative "storages/postgres"
+          PostgresStorage.new(cipher: cipher)
+        when :active_record
+          require_relative "storages/active_record"
+          ActiveRecordStorage.new(cipher: cipher)
+        else
+          raise Llmemory::ConfigurationError,
+                "Unsupported zero_mem trace store: #{resolved.inspect} " \
+                "(use :memory, :file, :postgres, or :active_record)"
+        end
+      end
+
+      def self.resolve_store
+        explicit = Llmemory.configuration.zero_mem_trace_store
+        return explicit if explicit && explicit.to_sym != :memory
+
+        case Llmemory.configuration.long_term_store.to_sym
+        when :file then :file
+        when :postgres then :postgres
+        when :active_record, :activerecord then :active_record
+        else
+          Llmemory.configuration.zero_mem_trace_store || :memory
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/trace.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+require "time"
+
+module Llmemory
+  module ZeroMem
+    class Trace
+      ATTRS = %i[
+        id user_id session_id boundary_id sequence role content occurred_at ingested_at
+        metadata content_sha256 idempotency_key archived_at
+      ].freeze
+
+      def self.build(user_id:, session_id:, role:, content:, sequence:, id: nil,
+                     boundary_id: nil, occurred_at: nil, ingested_at: nil, metadata: nil,
+                     idempotency_key: nil, archived_at: nil)
+        accepted = normalize_content!(content)
+        ingested = ingested_at || Time.now
+        occurred = occurred_at || ingested
+        meta = normalize_metadata(metadata)
+
+        new(
+          id: id || "tr_#{SecureRandom.hex(12)}",
+          user_id: user_id.to_s,
+          session_id: session_id.to_s,
+          boundary_id: boundary_id&.to_s,
+          sequence: sequence.to_i,
+          role: role.to_sym,
+          content: accepted,
+          occurred_at: coerce_time(occurred),
+          ingested_at: coerce_time(ingested),
+          metadata: meta,
+          content_sha256: Digest::SHA256.hexdigest(accepted),
+          idempotency_key: idempotency_key&.to_s,
+          archived_at: archived_at ? coerce_time(archived_at) : nil
+        )
+      end
+
+      def self.normalize_content!(content)
+        text = content.to_s
+        unless text.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+          raise ValidationError, "trace content must be valid UTF-8"
+        end
+
+        text = text.encode(Encoding::UTF_8)
+        max = Llmemory.configuration.max_message_chars.to_i
+        if max.positive? && text.length > max
+          raise ValidationError, "trace content exceeds max_message_chars (#{max})"
+        end
+
+        if Llmemory.configuration.message_sanitizer_enabled
+          sanitizer = Llmemory::ShortTerm::MessageSanitizer.new
+          sanitized = sanitizer.sanitize!([{ role: :user, content: text }])
+          text = sanitized.first[:content].to_s
+        end
+
+        text
+      end
+
+      def self.normalize_metadata(metadata)
+        return {} if metadata.nil?
+        raise ValidationError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+
+        metadata.transform_keys(&:to_sym)
+      end
+
+      def self.coerce_time(value)
+        return value if value.is_a?(Time)
+        return Time.parse(value.to_s) if value
+
+        Time.now
+      end
+
+      attr_reader(*ATTRS)
+
+      def initialize(**attrs)
+        ATTRS.each do |key|
+          instance_variable_set(:"@#{key}", attrs[key])
+        end
+      end
+
+      def to_h
+        ATTRS.each_with_object({}) do |key, acc|
+          val = public_send(key)
+          acc[key] = val.is_a?(Time) ? val.utc.iso8601(6) : val
+        end
+      end
+
+      def active?
+        archived_at.nil?
+      end
+
+      def with(**changes)
+        attrs = ATTRS.to_h { |key| [key, public_send(key)] }.merge(changes)
+        self.class.new(**attrs)
+      end
+    end
+  end
+end