delta_core 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d119d8a4706a021cd570aace06eaa040f0b6280e69d983860afde44b9628ed22
+  data.tar.gz: 35a89d6eda069c7e4e1346eda7d6eff7629225cbfc097f736b3985db2d788b40
+SHA512:
+  metadata.gz: 2aee8cff4e928582ae2b9e535f4dcd57b0b368feda2da2a8e85cec8a6cde3c24a595eeff12b3c0ba316d24580d3e91de8403f8bec5b3b6f1c933dbeb46173698
+  data.tar.gz: 46d1b0e0f5032b78888ca79f7f582f0670a81cf503a4b27e817c81b689833706859897b0f5c0c58eec91806ff66515b17c3c51237a32a9c05c3f19bf89f8c03f

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+## [Unreleased]
+## [1.0.0] - 2026-02-21
+
+- First stable release of DeltaCore (1.0.0).
+	- Added Rails DSL (`DeltaCore::DSL`) for declaring `snapshot_column` and `map` mappings.
+	- Implemented `StateBuilder` to serialize model associations into plain Hash state.
+	- Implemented `Comparator` with three built-in strategies: `:quantity`, `:replace`, and `:merge`.
+	- Added `Snapshot` persistence via `Adapters::ActiveRecord` and JSON column storage.
+	- Added `Context` flows: `delta_result` (calculate delta), `confirm_snapshot!` (update snapshot), and `with_delta_transaction`.
+	- Support for custom strategies and mapping extensions via registration APIs.
+
+## [0.1.0] - 2026-02-20
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"delta_core" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["mmarusyk1@gmail.com"](mailto:"mmarusyk1@gmail.com").

data/CONTRIBUTORS.md

@@ -0,0 +1,3 @@
+Contributors to DeltaCore gem include:
+
+* [Mykhailo Marusyk](https://github.com/mmarusyk)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mykhailo Marusyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,321 @@
+# DeltaCore
+
+DeltaCore persists explicit snapshots of confirmed class state and compares them
+against current state to produce structured, deterministic delta results. It distinguishes added,
+removed, and modified entities, supports pluggable comparison strategies (quantity, replace, and
+partial merge), and integrates with Rails via a configurable DSL with transactional safety and
+idempotent delta generation.
+
+## Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+```bash
+bundle add delta_core
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install delta_core
+```
+
+## Usage
+
+### Rails DSL
+
+Include the DSL in any class to configure snapshot behaviour and association mapping rules:
+
+```ruby
+class Order < ApplicationRecord
+  include DeltaCore::DSL
+
+  delta_core do
+    snapshot_column :order_delta_data
+
+    map :items,
+      key: :product_id,
+      fields: [:quantity, :unit_price],
+      strategy: :quantity,
+      relations: {
+        price_changes: {
+          key: :id,
+          fields: [:amount, :type],
+          strategy: :replace
+        }
+      }
+  end
+end
+```
+
+**Configuration options:**
+
+- `snapshot_column` — the column used to persist the serialized snapshot JSON on the record.
+- `map` — declares a top-level association to track. Accepts:
+  - `key:` — the unique identifier field used to match entities across snapshots.
+  - `fields:` — the list of comparable fields whose changes are detected. Only changes in these fields are captured.
+  - `strategy:` — comparison strategy for how changes are detected. One of:
+    - `:quantity` — Detects which items are added/removed by key, and which items have field changes.
+    - `:replace` — Treats the entire collection as a unit; if anything changes, the full collection is marked as added/removed.
+    - `:merge` — Like quantity, but also tracks which specific fields changed in modified items.
+  - `relations:` — optional nested association mapping, using the same key/fields/strategy options. Enables multi-level tracking.
+
+### Building State and Computing Deltas
+
+DeltaCore provides methods to inspect current state and compute deltas without persisting:
+
+```ruby
+# Get the structured state representation as a Hash
+state = order.delta_state
+# => { items: [...], price_changes: [...] }
+
+# Get the delta between the last snapshot and current state
+delta = order.delta_result
+delta.added    # => entities present in current state but absent from snapshot
+delta.removed  # => entities present in snapshot but absent from current state
+delta.modified # => entities present in both with changed field values
+delta.empty?   # => true when no differences exist (idempotent guard)
+```
+
+### Persisting Snapshots
+
+Snapshots are only persisted after external confirmation to avoid premature state capture. Choose 
+based on whether you need to confirm the delta before persisting:
+
+```ruby
+# Simple snapshot capture (raises EmptyDeltaError if no changes)
+order.confirm_snapshot!
+
+# Transactional flow with delta confirmation
+result = order.with_delta_transaction do |delta|
+  # Inspect delta, perform external operations
+  # Snapshot is persisted only if block completes successfully
+  external_api.submit(delta)
+  { success: true }
+end
+```
+
+### Resetting Delta Flags
+
+Clear any dirty-tracking metadata (extension point for custom implementations):
+
+```ruby
+order.reset_delta_flags!
+```
+
+## Architecture
+
+The diagram below covers every component in the system and the data flowing between them.
+Dashed arrows (`-.->`) denote interface implementation; solid arrows denote runtime data flow.
+
+```mermaid
+flowchart TD
+    subgraph setup["Setup Time"]
+        DSL["DSL: delta_core { }"]
+        Cfg["Configuration: snapshot_column · map"]
+        Map["Mapping: key · fields · strategy"]
+        DSL --> Cfg
+        Cfg --> Map
+        Map -->|nested relations| Map
+    end
+
+    Model(["AR Model Instance"])
+    setup -->|config stored on class| Model
+
+    Ctx["Context: build_state · calculate_delta · update_snapshot · with_delta_transaction"]
+    Model --> Ctx
+
+    subgraph storage["Storage"]
+        AB["Adapters::Base: interface"]
+        AAR["Adapters::ActiveRecord: load_snapshot · persist · lock_record"]
+        Snap["Snapshot: parse · serialize · empty?"]
+        DB[("PostgreSQL")]
+        AB -. implements .-> AAR
+        AAR <-->|load / persist| Snap
+        Snap <-->|read / write| DB
+    end
+
+    subgraph state["State Building"]
+        SB["StateBuilder: extract AR associations → plain Hash"]
+    end
+
+    subgraph comparison["Comparison"]
+        Cmp["Comparator: resolve strategy · merge results"]
+        SBase["Strategies::Base: interface"]
+        SQty["Strategies::Quantity: by key with field changes"]
+        SRep["Strategies::Replace: full replacement on any change"]
+        SMrg["Strategies::Merge: by key + track changed fields"]
+        Cmp -->|delegates to| SBase
+        SBase -. implements .-> SQty
+        SBase -. implements .-> SRep
+        SBase -. implements .-> SMrg
+    end
+
+    DR(["DeltaResult: added · removed · modified"])
+
+    Ctx -->|build current state| SB
+    Ctx -->|load · lock · persist| AAR
+    Map -->|mapping rules| SB
+    Map -->|mapping rules| Cmp
+    SB -->|current state Hash| Cmp
+    Snap -->|snapshot state Hash| Cmp
+    Cmp -->|merged output| DR
+```
+
+### Key flows
+
+**`build_state`** — Calls `StateBuilder` to extract a plain Hash representation of all mapped 
+associations and their fields from the model. Used by both delta computation and snapshot updates.
+
+**`calculate_delta`** (or `delta_result`) — `Context` calls `StateBuilder` to produce current 
+state, loads the persisted `Snapshot` via `Adapters::ActiveRecord`, then passes both into 
+`Comparator`. For each `Mapping`, `Comparator` resolves the configured strategy
+(`Quantity` / `Replace` / `Merge`) via `Strategies::Base` and merges the results into a
+`DeltaResult`.
+
+**`update_snapshot`** (or `confirm_snapshot!`) — Calculates delta and raises `EmptyDeltaError` 
+if no changes exist. Acquires a record lock through `Adapters::ActiveRecord`, rebuilds current 
+state via `StateBuilder`, serializes it through `Snapshot`, and persists the JSON back to the 
+PostgreSQL column. The snapshot never advances if transmission fails.
+
+**`with_delta_transaction`** — Combines delta calculation and snapshot persistence in a single 
+transactional block. Acquires a lock, calculates the delta, yields to the block for external 
+processing, and only persists the snapshot if the block completes successfully without raising.
+
+## Extension Points
+
+### Custom Strategies
+
+Register custom comparison strategies using the global strategy registry:
+
+```ruby
+# Define a custom strategy
+module MyStrategy
+  def self.call(snapshot_collection, current_collection, mapping)
+    # Return hash with :added, :removed, :modified keys
+    { added: [], removed: [], modified: [] }
+  end
+end
+
+# Register it
+DeltaCore.register_strategy(:my_strategy, MyStrategy)
+
+# Use it in configuration
+class Order < ApplicationRecord
+  include DeltaCore::DSL
+
+  delta_core do
+    snapshot_column :delta_data
+    map :items, key: :id, fields: [:amount], strategy: :my_strategy
+  end
+end
+```
+
+### Mapping Extensions
+
+Extend the state builder to add computed fields or custom transformations to entities:
+
+```ruby
+DeltaCore.register_mapping_extension(->(entity, record, mapping) {
+  # Add computed fields to entity
+  entity[:computed_field] = record.some_method
+  entity
+})
+```
+
+### Custom Adapters
+
+Implement the `Adapters::Base` interface to use a different persistence backend:
+
+```ruby
+class MyAdapter
+  def load_snapshot(model)
+    # Return a Snapshot instance
+  end
+
+  def persist(model, serialized_json)
+    # Save the JSON somewhere
+  end
+
+  def lock_record(model, &block)
+    # Ensure thread-safe execution
+    yield
+  end
+end
+
+# Use it
+config = DeltaCore::Configuration.new
+config.snapshot_column :delta_data
+context = DeltaCore::Context.new(config, adapter: MyAdapter.new)
+```
+
+## Comparison Strategies
+
+DeltaCore provides three built-in comparison strategies for detecting changes in collections:
+
+### `:quantity`
+
+Detects additions and removals by matching entities on the configured `:key` field. For matched 
+pairs, compares the `:fields` and reports any that changed.
+
+**Use when:** You want to track individual entity changes and need to distinguish between 
+added, removed, and modified entities within a collection.
+
+```ruby
+# Example: Track order items by product_id
+map :items, key: :product_id, fields: [:quantity, :price], strategy: :quantity
+# Result: Shows which items were added/removed and which had quantity/price changes
+```
+
+### `:replace`
+
+Treats the entire collection as a single unit. If any element in the collection differs, 
+the entire collection is reported as removed (old) and added (new).
+
+**Use when:** The collection should be treated as an atomic whole, such as a JSON array 
+or blob that's either changed entirely or not at all.
+
+```ruby
+# Example: Track metadata that's stored as a complete JSON structure
+map :tags, key: :name, fields: [:value], strategy: :replace
+# Result: Either the full tags collection is reported as modified, or nothing changed
+```
+
+### `:merge`
+
+Like `:quantity`, but additionally tracks which specific `:fields` changed in each modified 
+entity. The `modified` results include a `changed_fields` array.
+
+**Use when:** You need fine-grained information about exactly which fields changed per entity.
+
+```ruby
+# Example: Track price adjustments with detailed field-level changes
+map :prices, key: :currency, fields: [:amount, :type], strategy: :merge
+# Result: Shows which prices changed AND which fields (amount vs type) were modified
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to
+run the tests. You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`,
+which will create a git tag for the version, push git commits and the created tag, and push the
+`.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mmarusyk/delta_core.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are
+expected to adhere to the [code of conduct](https://github.com/mmarusyk/delta_core/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the DeltaCore project's codebases, issue trackers, chat rooms and mailing
+lists is expected to follow the [code of conduct](https://github.com/mmarusyk/delta_core/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+# Set SOURCE_DATE_EPOCH to the last git commit date for reproducible builds
+# This ensures Ruby Toolbox and other tools can properly detect release dates
+# See: https://github.com/rubytoolbox/rubytoolbox/issues/1653
+ENV["SOURCE_DATE_EPOCH"] ||= `git log -1 --format=%cd --date=unix`.chomp
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/delta_core/adapters/active_record.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  module Adapters
+    class ActiveRecord
+      include Base
+
+      def initialize(config)
+        @config = config
+      end
+
+      def load_snapshot(model)
+        raw = model.public_send(@config.snapshot_column)
+        Snapshot.new(raw)
+      end
+
+      def persist(model, serialized_json)
+        model.update_column(@config.snapshot_column, serialized_json)
+      end
+
+      def lock_record(model, &)
+        model.with_lock(&)
+      end
+    end
+  end
+end

data/lib/delta_core/adapters/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  module Adapters
+    module Base
+      def load_snapshot(_model)
+        raise NotImplementedError, "#{self.class}#load_snapshot not implemented"
+      end
+
+      def persist(_model, _serialized_json)
+        raise NotImplementedError, "#{self.class}#persist not implemented"
+      end
+
+      def lock_record(_model)
+        raise NotImplementedError, "#{self.class}#lock_record not implemented"
+      end
+    end
+  end
+end

data/lib/delta_core/comparator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  class Comparator
+    BUILT_IN_STRATEGIES = {
+      quantity: Strategies::Quantity,
+      replace: Strategies::Replace,
+      merge: Strategies::Merge
+    }.freeze
+
+    def self.compare(snapshot_state, current_state, config)
+      new(snapshot_state, current_state, config).compare
+    end
+
+    def initialize(snapshot_state, current_state, config)
+      @snapshot_state = snapshot_state
+      @current_state  = current_state
+      @config         = config
+    end
+
+    def compare
+      @config.mappings.reduce(DeltaResult.new) do |result, mapping|
+        snap_coll = Array(@snapshot_state[mapping.name])
+        curr_coll = Array(@current_state[mapping.name])
+
+        strategy = resolve_strategy(mapping.strategy)
+        raw      = strategy.call(snap_coll, curr_coll, mapping)
+        partial  = DeltaResult.new(**raw)
+        nested   = compare_nested(snap_coll, curr_coll, mapping)
+
+        result.merge(partial).merge(nested)
+      end
+    end
+
+    private
+
+    def resolve_strategy(name)
+      BUILT_IN_STRATEGIES[name] ||
+        DeltaCore.strategy_registry[name] ||
+        raise(ArgumentError, "Unknown strategy: #{name.inspect}")
+    end
+
+    def compare_nested(snap_coll, curr_coll, mapping)
+      return DeltaResult.new if mapping.relations.empty?
+
+      snap_idx = Strategies::Base.index_by_key(snap_coll, mapping.key)
+      curr_idx = Strategies::Base.index_by_key(curr_coll, mapping.key)
+
+      mapping.relations.reduce(DeltaResult.new) do |rel_result, (rel_name, rel_mapping)|
+        curr_idx.reduce(rel_result) do |inner_result, (_, curr_entity)|
+          key_val     = curr_entity[mapping.key]
+          snap_entity = snap_idx[key_val] || {}
+          snap_nested = Array(snap_entity[rel_name])
+          curr_nested = Array(curr_entity[rel_name])
+
+          nested_snap = { rel_mapping.name => snap_nested }
+          nested_curr = { rel_mapping.name => curr_nested }
+          nested_cfg  = build_nested_config(rel_mapping)
+
+          partial = self.class.compare(nested_snap, nested_curr, nested_cfg)
+          inner_result.merge(partial)
+        end
+      end
+    end
+
+    def build_nested_config(rel_mapping)
+      cfg = Configuration.new
+      cfg.instance_variable_set(:@mappings, [rel_mapping])
+      cfg
+    end
+  end
+end

data/lib/delta_core/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  class Configuration
+    attr_reader :mappings
+
+    def initialize
+      @snapshot_column = nil
+      @mappings        = []
+    end
+
+    def snapshot_column(column_name = nil)
+      if column_name
+        @snapshot_column = column_name.to_sym
+      else
+        @snapshot_column
+      end
+    end
+
+    def map(name, key:, strategy:, fields: [], relations: {})
+      sym = name.to_sym
+      raise ArgumentError, "Duplicate mapping: #{sym}" if mapping_names.include?(sym)
+
+      mapping = Mapping.new(sym, key: key, fields: fields, strategy: strategy, relations: relations)
+      @mappings << mapping
+      mapping
+    end
+
+    private
+
+    def mapping_names
+      @mappings.map(&:name)
+    end
+  end
+end

data/lib/delta_core/context.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  class Context
+    def initialize(config, adapter: nil)
+      @config  = config
+      @adapter = adapter || Adapters::ActiveRecord.new(config)
+    end
+
+    def build_state(model)
+      StateBuilder.build(model, @config)
+    end
+
+    def calculate_delta(model)
+      snapshot      = @adapter.load_snapshot(model)
+      current_state = build_state(model)
+      Comparator.compare(snapshot.state, current_state, @config)
+    end
+
+    def update_snapshot(model)
+      delta = calculate_delta(model)
+      raise EmptyDeltaError, "Cannot update snapshot: delta is empty" if delta.empty?
+
+      @adapter.lock_record(model) do
+        current_state  = build_state(model)
+        serialized     = Snapshot.new.serialize(current_state)
+        @adapter.persist(model, serialized)
+      end
+    end
+
+    def with_delta_transaction(model)
+      raise ArgumentError, "Block required" unless block_given?
+
+      result = nil
+
+      @adapter.lock_record(model) do
+        current_state = build_state(model)
+        delta         = Comparator.compare(
+          @adapter.load_snapshot(model).state,
+          current_state,
+          @config
+        )
+
+        raise EmptyDeltaError, "Delta is empty — nothing to transmit" if delta.empty?
+
+        result = yield delta
+
+        serialized = Snapshot.new.serialize(current_state)
+        @adapter.persist(model, serialized)
+      end
+
+      result
+    end
+
+    def reset_flags(_model)
+      # Extension point: clears any dirty-tracking metadata.
+      # Default implementation is a no-op.
+    end
+  end
+end

data/lib/delta_core/delta_result.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  class DeltaResult
+    attr_reader :added, :removed, :modified
+
+    def initialize(added: [], removed: [], modified: [])
+      @added    = Array(added).freeze
+      @removed  = Array(removed).freeze
+      @modified = Array(modified).freeze
+      freeze
+    end
+
+    def empty?
+      added.empty? && removed.empty? && modified.empty?
+    end
+
+    def merge(other)
+      self.class.new(
+        added: added + other.added,
+        removed: removed + other.removed,
+        modified: modified + other.modified
+      )
+    end
+
+    def render(renderer)
+      renderer.call(self)
+    end
+  end
+end

data/lib/delta_core/dsl.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  module DSL
+    module ClassMethods
+      def delta_core(&)
+        config = Configuration.new
+        config.instance_eval(&)
+        @delta_core_config = config
+
+        include InstanceMethods
+      end
+
+      def delta_core_config
+        @delta_core_config
+      end
+    end
+
+    module InstanceMethods
+      def delta_state
+        DeltaCore::Context.new(self.class.delta_core_config).build_state(self)
+      end
+
+      def delta_result
+        DeltaCore::Context.new(self.class.delta_core_config).calculate_delta(self)
+      end
+
+      def confirm_snapshot!
+        DeltaCore::Context.new(self.class.delta_core_config).update_snapshot(self)
+      end
+
+      def reset_delta_flags!
+        DeltaCore::Context.new(self.class.delta_core_config).reset_flags(self)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+
+  Model = DSL
+
+  ::ActiveRecord::Base.include(DSL) if defined?(::ActiveRecord::Base)
+end

data/lib/delta_core/mapping.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  class Mapping
+    attr_reader :name, :key, :fields, :strategy, :relations
+
+    def initialize(name, key:, strategy:, fields: [], relations: {})
+      @name      = name.to_sym
+      @key       = key.to_sym
+      @fields    = Array(fields).map(&:to_sym)
+      @strategy  = strategy.to_sym
+      @relations = build_relations(relations || {})
+    end
+
+    private
+
+    def build_relations(raw)
+      raw.each_with_object({}) do |(assoc_name, opts), result|
+        result[assoc_name.to_sym] = Mapping.new(
+          assoc_name,
+          key: opts.fetch(:key),
+          fields: opts.fetch(:fields, []),
+          strategy: opts.fetch(:strategy),
+          relations: opts.fetch(:relations, {})
+        )
+      end
+    end
+  end
+end

data/lib/delta_core/renderer/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  module Renderer
+    module Base
+      def call(_delta_result)
+        raise NotImplementedError, "#{self.class}#call not implemented"
+      end
+    end
+  end
+end

data/lib/delta_core/snapshot.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  class Snapshot
+    FORMAT_VERSION = 1
+    VERSION_KEY    = "_v"
+
+    attr_reader :state
+
+    def initialize(raw = nil)
+      @state = parse(raw)
+    end
+
+    def empty?
+      @state.empty?
+    end
+
+    def serialize(current_state)
+      payload = { VERSION_KEY => FORMAT_VERSION }
+      payload.merge!(stringify_keys(current_state))
+      JSON.generate(payload)
+    end
+
+    private
+
+    def parse(raw)
+      return {} if raw.nil? || raw.to_s.strip.empty?
+
+      parsed = JSON.parse(raw.to_s, symbolize_names: true)
+      return {} unless parsed.is_a?(Hash)
+
+      parsed.except(:_v)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def stringify_keys(hash)
+      hash.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/delta_core/state_builder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  class StateBuilder
+    @extensions = []
+
+    class << self
+      attr_reader :extensions
+
+      def build(model, config)
+        new(model, config).build
+      end
+    end
+
+    def initialize(model, config)
+      @model  = model
+      @config = config
+    end
+
+    def build
+      @config.mappings.each_with_object({}) do |mapping, state|
+        state[mapping.name] = build_collection(mapping)
+      end
+    end
+
+    private
+
+    def build_collection(mapping)
+      collection = @model.public_send(mapping.name)
+      Array(collection)
+        .map { |record| build_record(record, mapping) }
+        .sort_by { |h| h[mapping.key].to_s }
+    end
+
+    def build_record(record, mapping)
+      entity = { mapping.key => extract_value(record, mapping.key) }
+
+      mapping.fields.each do |field|
+        entity[field] = extract_value(record, field)
+      end
+
+      mapping.relations.each do |assoc_name, rel_mapping|
+        entity[assoc_name] = build_nested(record, rel_mapping)
+      end
+
+      apply_extensions(entity, record, mapping)
+    end
+
+    def build_nested(record, rel_mapping)
+      collection = record.public_send(rel_mapping.name)
+      Array(collection)
+        .map { |r| build_record(r, rel_mapping) }
+        .sort_by { |h| h[rel_mapping.key].to_s }
+    end
+
+    def extract_value(record, field)
+      record.public_send(field)
+    end
+
+    def apply_extensions(entity, record, mapping)
+      self.class.extensions.reduce(entity) do |e, ext|
+        ext.respond_to?(:call) ? ext.call(e, record, mapping) : e
+      end
+    end
+  end
+end

data/lib/delta_core/strategies/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  module Strategies
+    module Base
+      def self.call(_snapshot_collection, _current_collection, _mapping)
+        raise NotImplementedError, "#{name} must implement .call"
+      end
+
+      def self.index_by_key(collection, key)
+        collection.each_with_object({}) do |entity, idx|
+          idx[entity[key]] = entity
+        end
+      end
+    end
+  end
+end

data/lib/delta_core/strategies/merge.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  module Strategies
+    module Merge
+      def self.call(snapshot_collection, current_collection, mapping)
+        snap_index = Base.index_by_key(snapshot_collection, mapping.key)
+        curr_index = Base.index_by_key(current_collection, mapping.key)
+
+        added   = curr_index.reject { |k, _| snap_index.key?(k) }.values
+        removed = snap_index.reject { |k, _| curr_index.key?(k) }.values
+
+        modified = curr_index.filter_map do |k, curr|
+          snap = snap_index[k]
+          next unless snap
+
+          changed_fields = mapping.fields.reject { |f| curr[f] == snap[f] }
+          next if changed_fields.empty?
+
+          { current: curr, snapshot: snap, changed_fields: changed_fields }
+        end
+
+        { added: added, removed: removed, modified: modified }
+      end
+    end
+  end
+end

data/lib/delta_core/strategies/quantity.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  module Strategies
+    module Quantity
+      def self.call(snapshot_collection, current_collection, mapping)
+        snap_index = Base.index_by_key(snapshot_collection, mapping.key)
+        curr_index = Base.index_by_key(current_collection, mapping.key)
+
+        added   = curr_index.reject { |k, _| snap_index.key?(k) }.values
+        removed = snap_index.reject { |k, _| curr_index.key?(k) }.values
+
+        modified = curr_index.filter_map do |k, curr|
+          snap = snap_index[k]
+          next unless snap
+
+          changed = mapping.fields.any? { |f| curr[f] != snap[f] }
+          { current: curr, snapshot: snap } if changed
+        end
+
+        { added: added, removed: removed, modified: modified }
+      end
+    end
+  end
+end

data/lib/delta_core/strategies/replace.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  module Strategies
+    module Replace
+      def self.call(snapshot_collection, current_collection, _mapping)
+        return { added: [], removed: [], modified: [] } if snapshot_collection == current_collection
+
+        { added: current_collection, removed: snapshot_collection, modified: [] }
+      end
+    end
+  end
+end

data/lib/delta_core/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DeltaCore
+  VERSION = "1.0.0"
+end

data/lib/delta_core.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "delta_core/version"
+require_relative "delta_core/mapping"
+require_relative "delta_core/configuration"
+require_relative "delta_core/delta_result"
+require_relative "delta_core/snapshot"
+require_relative "delta_core/state_builder"
+require_relative "delta_core/strategies/base"
+require_relative "delta_core/strategies/quantity"
+require_relative "delta_core/strategies/replace"
+require_relative "delta_core/strategies/merge"
+require_relative "delta_core/comparator"
+require_relative "delta_core/adapters/base"
+require_relative "delta_core/adapters/active_record"
+require_relative "delta_core/context"
+require_relative "delta_core/renderer/base"
+require_relative "delta_core/dsl"
+
+module DeltaCore
+  class Error < StandardError; end
+  class EmptyDeltaError < Error; end
+
+  @strategy_registry = {}
+
+  class << self
+    attr_reader :strategy_registry
+
+    def register_strategy(name, klass)
+      @strategy_registry[name.to_sym] = klass
+    end
+
+    def register_mapping_extension(callable)
+      StateBuilder.extensions << callable
+    end
+  end
+end

data/sig/delta_core.rbs

@@ -0,0 +1,4 @@
+module DeltaCore
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: delta_core
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mykhailo Marusyk
+bindir: exe
+cert_chain: []
+date: 2026-02-21 00:00:00.000000000 Z
+dependencies: []
+description: DeltaCore persists explicit snapshots of confirmed class state and compares
+  them against current state to produce structured, deterministic delta results. It
+  distinguishes added, removed, and modified entities, supports pluggable comparison
+  strategies (quantity, replace, merge), and integrates with Rails via a configurable
+  DSL with transactional safety and idempotent delta generation.
+email:
+- mmarusyk1@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTORS.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/delta_core.rb
+- lib/delta_core/adapters/active_record.rb
+- lib/delta_core/adapters/base.rb
+- lib/delta_core/comparator.rb
+- lib/delta_core/configuration.rb
+- lib/delta_core/context.rb
+- lib/delta_core/delta_result.rb
+- lib/delta_core/dsl.rb
+- lib/delta_core/mapping.rb
+- lib/delta_core/renderer/base.rb
+- lib/delta_core/snapshot.rb
+- lib/delta_core/state_builder.rb
+- lib/delta_core/strategies/base.rb
+- lib/delta_core/strategies/merge.rb
+- lib/delta_core/strategies/quantity.rb
+- lib/delta_core/strategies/replace.rb
+- lib/delta_core/version.rb
+- sig/delta_core.rbs
+homepage: https://github.com/mmarusyk/delta_core
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/mmarusyk/delta_core
+  source_code_uri: https://github.com/mmarusyk/delta_core
+  changelog_uri: https://github.com/mmarusyk/delta_core/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Snapshot, compare, and diff class state with structured delta results.
+test_files: []