rangeable 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b0a56ae009cc8892842f7b40ca828a0aa0f716c389b58b2e172afe08bca8e70
+  data.tar.gz: 67ecd4f99e0e9857a952301eacc7564507d1d0c422a9ee61b2e34eb141ad852d
+SHA512:
+  metadata.gz: 119170a145bf1229fc3777caa8d6c7747349cd9f8a05cf5411b609b01ff22d2b28a1914d4eaa3494dfccbf6a9f40716e2456662b4cf507c8479f0c5071ddaba1
+  data.tar.gz: 2e76959c07b80799a06b5f01aedaa71d807f3a842be70e4565bf38aed64b3a860d1b7380aa1f9c125e18aa4d1bab5ca59f548e27cb48b0b97cfdad8034fd6c15

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-05-10
+
+### Added
+
+- Initial public release of `Rangeable<Element>`, the Ruby reference implementation of [RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC).
+- Per-element sorted disjoint-interval list with idempotent containment fast-path.
+- Lazy boundary-event index, rebuilt on the next read after a mutating insert; version-counter based invalidation.
+- Public API: `insert(element, start:, end:)`, `[i].objs`, `get_range(element)`, `transitions(over:)`, `count`, `empty?`, `each`, `copy`.
+- Refinement-style sugar `using Rangeable::Refinements` to enable `element.get_range(from: r)` without polluting `Object`.
+- Full RFC § 10 normative test contract (23 tests) plus a 1000-iteration property test against a brute-force oracle and a markdown-shaped micro-benchmark.
+- Cross-language fixture (160 ops, 86 probes) shared with the Swift reference implementation; outputs are byte-identical.
+
+### Performance
+
+- Micro-benchmark: ~5.5× speedup over brute-force at m=50, L=2000.
+- Real-world consumer ([ZMediumToMarkdown](https://github.com/ZhgChgLi/ZMediumToMarkdown)): 2.23× end-to-end speedup, 55% render-time reduction; all 306 existing tests pass byte-identical.
+
+### Specification
+
+- Conforms to [RangeableRFC v1.0](https://github.com/ZhgChgLi/RangeableRFC), reviewed and APPROVED by an independent academic reviewer (round 2; round-1 verdict REJECTED with 6 MUST-FIX items addressed).
+
+[1.0.0]: https://github.com/ZhgChgLi/RubyRangeable/releases/tag/v1.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZhgChgLi
+
+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,115 @@
+# RubyRangeable
+
+[![Gem Version](https://img.shields.io/gem/v/rangeable)](https://rubygems.org/gems/rangeable) [![Ruby](https://img.shields.io/badge/ruby-3.2%2B-red)]() [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Reference Ruby implementation of [`Rangeable<Element>`](https://github.com/ZhgChgLi/RangeableRFC) — a generic, integer-coordinate, closed-interval set container with first-insert ordered active queries.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'rangeable', '~> 1.0'
+```
+
+Or install directly:
+
+```sh
+$ gem install rangeable
+```
+
+## Usage
+
+```ruby
+require 'rangeable'
+
+# Any Ruby object with sensible == / hash works as an element.
+Strong = Struct.new(:tag)
+Italic = Struct.new(:tag)
+
+r = Rangeable.new
+r.insert(Strong.new(:bold), start: 2, end: 5)
+r.insert(Strong.new(:bold), start: 3, end: 7)   # merges with [2, 5] → [2, 7]
+r.insert(Strong.new(:bold), start: 9, end: 11)  # disjoint
+r.insert(Italic.new(:em),   start: 3, end: 8)
+
+r.get_range(Strong.new(:bold))  # => [[2, 7], [9, 11]]
+r.get_range(Italic.new(:em))    # => [[3, 8]]
+
+r[4].objs   # => [Strong<:bold>, Italic<:em>]   first-insert order
+r[8].objs   # => [Italic<:em>]
+r[10].objs  # => [Strong<:bold>]
+```
+
+### Refinement sugar
+
+Avoid polluting the global namespace:
+
+```ruby
+using Rangeable::Refinements
+
+Strong.new(:bold).get_range(from: r)  # => [[2, 7], [9, 11]]
+```
+
+### Sweep iteration via transitions
+
+```ruby
+r.transitions(over: 0..15).each do |event|
+  case event.kind
+  when :open  then puts "#{event.coordinate}: open #{event.element}"
+  when :close then puts "#{event.coordinate}: close #{event.element}"
+  end
+end
+```
+
+## API
+
+| Method | Returns | Notes |
+|---|---|---|
+| `Rangeable.new` | empty `Rangeable` | |
+| `r.insert(element, start:, end:)` | `:mutated` / `:idempotent` | raises `Rangeable::InvalidIntervalError` if `start > end` |
+| `r[i]` | `Rangeable::Slot` | wrapper exposing `.objs` |
+| `r[i].objs` | frozen `Array<Element>` | first-insert order |
+| `r.get_range(element)` | `Array<[lo, hi]>` | merged disjoint ranges |
+| `r.transitions(over: a..b)` | `Array<Event>` | each `Event` has `coordinate`, `kind`, `element` |
+| `r.count` | `Integer` | distinct elements |
+| `r.empty?` | `Boolean` | |
+| `r.each { \|element, ranges\| ... }` | `self` | iteration |
+| `r.copy` | `Rangeable` | deep copy |
+
+## Semantics
+
+- **End is inclusive**: `[a, b]` covers `a..b`, both ends.
+- **Same-element merging**: equal elements (by `==` / `hash`) merge on overlap or integer adjacency. `[2, 4] ∪ [5, 7] = [2, 7]`.
+- **Idempotent insert**: re-inserting a contained interval costs no version bump.
+- **Out-of-order rejected**: `insert(_, start: 5, end: 2)` raises.
+- **Active-set ordering**: deterministic across runs — first-insert order of the element, not hash bucket order.
+- **Element immutability**: elements are frozen on insert (`element.dup.freeze`); mutating an element after insert is undefined behaviour.
+
+See [RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC) § 4 for normative semantics, § 6 for algorithms, § 7 for the Φ-potential amortised-complexity proof, and § 10 for the 23-case normative test contract this gem must pass.
+
+## Performance
+
+| Workload | Result |
+|---|---|
+| Brute-force baseline (m=50, L=2000) vs `Rangeable` | **~5.5× speedup** in micro-benchmark |
+| Real consumer ([ZMediumToMarkdown](https://github.com/ZhgChgLi/ZMediumToMarkdown)) | **2.23× end-to-end speedup**, 55% render-time reduction; all 306 existing tests byte-identical |
+
+## See also
+
+- **[RangeableRFC](https://github.com/ZhgChgLi/RangeableRFC)** — the normative specification this gem implements.
+- **[SwiftRangeable](https://github.com/ZhgChgLi/SwiftRangeable)** — sibling reference implementation in Swift; produces byte-identical outputs against a shared cross-language fixture.
+- **[ZMediumToMarkdown](https://github.com/ZhgChgLi/ZMediumToMarkdown)** — real-world consumer that exercises this gem on Medium GraphQL renderers.
+
+## Development
+
+```sh
+$ bundle install
+$ bundle exec rake test
+```
+
+The test suite covers the full RFC § 10 contract (23 normative tests), a 1000-iteration property test against a brute-force oracle, and a markdown-shaped micro-benchmark.
+
+## License
+
+MIT © [ZhgChgLi](https://github.com/ZhgChgLi)

data/lib/rangeable/boundary_index.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+class Rangeable
+  # Lazy boundary-event index per RFC §5.2 / §6.3.
+  #
+  # Built from a snapshot of the per-element interval map plus the
+  # insertion-order map `ord`. Carries:
+  #
+  #   * `events`   — sorted Array of TransitionEvent under §4.5 ordering.
+  #   * `segments` — sorted, disjoint Array of (seg_lo, seg_hi, frozen active)
+  #                  triples covering every coordinate at which the active
+  #                  set is non-empty. Active sets are frozen and sorted by
+  #                  `ord(e)` ascending.
+  #   * `version`  — snapshot of Rangeable.version at build time. The owner
+  #                  Rangeable invalidates the index by setting it to nil
+  #                  on any mutation; reads compare versions to decide
+  #                  whether to rebuild (T3 mutex pattern, §11).
+  #
+  # `nil` close coordinates encode +∞ for hi == Integer::MAX boundaries
+  # (§4.7 C4). Comparison against `nil` always treats it as greater than
+  # any finite Integer; we centralise that logic in `coord_lt?` /
+  # `coord_le?`.
+  class BoundaryIndex
+    # Public TransitionEvent type returned by `Rangeable#transitions`.
+    # `coordinate` is normally an Integer; it is `nil` for close events
+    # whose underlying interval ends at the implementation's +∞ sentinel
+    # (i.e. `hi` was the maximum representable boundary in the cross-language
+    # contract). `kind` is `:open` or `:close`.
+    TransitionEvent = Struct.new(:coordinate, :kind, :element, :ord) do
+      def open?
+        kind == :open
+      end
+
+      def close?
+        kind == :close
+      end
+
+      def to_h
+        { coordinate: coordinate, kind: kind, element: element }
+      end
+    end
+
+    # Sentinel: callers may pass `Integer.MAX` semantics by passing the
+    # special value below as `hi`. We default to no upper bound so close
+    # coords are always `hi + 1` finite Integer except when the caller
+    # explicitly opts into the +∞ sentinel via `Rangeable::INT_MAX`.
+    #
+    # Ruby has unbounded Integer, so this sentinel only matters for
+    # cross-language byte-identical fixtures that need to round-trip
+    # Swift's `Int.max` boundary (Test #23.A).
+
+    Segment = Struct.new(:lo, :hi, :active)
+
+    attr_reader :events, :segments, :version
+
+    def initialize(events, segments, version)
+      @events   = events.freeze
+      @segments = segments.freeze
+      @version  = version
+      freeze
+    end
+
+    # Find the segment containing `coord`, or nil if none. O(log |segments|).
+    # `coord` must be a finite Integer.
+    def segment_at(coord)
+      idx = @segments.bsearch_index { |seg| seg.hi >= coord }
+      return nil unless idx
+
+      seg = @segments[idx]
+      return nil unless seg.lo <= coord
+      seg
+    end
+
+    # Returns the events whose coordinate falls in `[lo, succ(hi)]` per
+    # RFC §6.4. `lo` is a finite Integer; `upper_coord` may be `nil` to
+    # mean "include all events through +∞".
+    def events_in_range(lo, upper_coord)
+      i_start = @events.bsearch_index { |ev| coord_ge?(ev.coordinate, lo) } || @events.size
+      result = []
+      i = i_start
+      while i < @events.size && coord_le?(@events[i].coordinate, upper_coord)
+        result << @events[i]
+        i += 1
+      end
+      result
+    end
+
+    # Build a fresh index from the per-element interval map and the
+    # insertion-order map `ord`. `int_max_sentinel` (default nil) lets the
+    # caller opt into "treat hi == sentinel as +∞" semantics for cross-
+    # language fixture parity; if it is nil we never coerce close coords
+    # to nil (Ruby's unbounded Integer makes that unnecessary).
+    def self.build(intervals, ord, snapshot_version, int_max_sentinel: nil)
+      events = []
+      intervals.each do |element, set|
+        element_ord = ord[element]
+        set.each do |interval|
+          events << TransitionEvent.new(interval.lo, :open, element, element_ord)
+          close_coord =
+            if !int_max_sentinel.nil? && interval.hi == int_max_sentinel
+              nil
+            else
+              interval.hi + 1
+            end
+          events << TransitionEvent.new(close_coord, :close, element, element_ord)
+        end
+      end
+
+      events.sort! do |a, b|
+        cmp = compare_coord(a.coordinate, b.coordinate)
+        next cmp unless cmp.zero?
+
+        # Same coord: opens before closes.
+        cmp = (a.kind == :open ? 0 : 1) <=> (b.kind == :open ? 0 : 1)
+        next cmp unless cmp.zero?
+
+        # Same coord + same kind: open ascending by ord, close descending.
+        if a.kind == :open
+          a.ord <=> b.ord
+        else
+          b.ord <=> a.ord
+        end
+      end
+
+      segments = materialise_segments(events)
+      new(events, segments, snapshot_version)
+    end
+
+    # Sweep events linearly, materialising a Segment for every maximal run
+    # of integers over which the active set is constant. Per RFC §6.3 we
+    # do not emit a segment whose active set is empty (no phantom
+    # `(-inf, first_open - 1)` segment).
+    def self.materialise_segments(events)
+      segments = []
+      active_by_ord = {} # ord => element (treated as a sorted set keyed by ord)
+      prev_coord = nil
+      i = 0
+      while i < events.size
+        # Group events at the same coord; we apply all of them before
+        # snapshotting the active set so that segment boundaries land on
+        # transitions, not in the middle of a same-coord burst.
+        ev = events[i]
+        coord = ev.coordinate
+
+        if !prev_coord.nil? && !active_by_ord.empty?
+          segments << Segment.new(prev_coord, coord - 1, snapshot_active(active_by_ord))
+        end
+
+        # Apply every event at this coord.
+        while i < events.size && events[i].coordinate == coord
+          ev_i = events[i]
+          if ev_i.open?
+            active_by_ord[ev_i.ord] = ev_i.element
+          else
+            active_by_ord.delete(ev_i.ord)
+          end
+          i += 1
+        end
+
+        prev_coord = coord
+      end
+      segments
+    end
+
+    # Snapshot the active set as a frozen Array sorted by ord ascending.
+    # The Hash insertion order is not guaranteed to match ord ascending
+    # (we add/remove arbitrarily), so we sort explicitly.
+    def self.snapshot_active(active_by_ord)
+      active_by_ord.keys.sort.map { |o| active_by_ord[o] }.freeze
+    end
+
+    # Total order over coordinates: nil (== +∞) is greater than any finite.
+    # Returns -1 / 0 / +1.
+    def self.compare_coord(a, b)
+      return 0 if a.nil? && b.nil?
+      return 1 if a.nil?
+      return -1 if b.nil?
+
+      a <=> b
+    end
+
+    private
+
+    def coord_ge?(coord, threshold)
+      self.class.compare_coord(coord, threshold) >= 0
+    end
+
+    def coord_le?(coord, upper)
+      self.class.compare_coord(coord, upper) <= 0
+    end
+  end
+end

data/lib/rangeable/disjoint_set.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'interval'
+
+class Rangeable
+  # Sorted, disjoint, non-adjacent list of `Interval` for a single element.
+  #
+  # Maintains RFC §5.1 (I1) invariant:
+  #   * sorted by lo strictly ascending
+  #   * any two adjacent entries (lo1, hi1), (lo2, hi2) satisfy hi1 + 1 < lo2
+  #     (no overlap, no integer adjacency)
+  #   * lo <= hi for every entry
+  #
+  # `insert` follows RFC §6.1 cleaner variant (containment idempotent
+  # fast-path) and signals to the caller whether the mutation actually
+  # changed the canonical state.
+  class DisjointSet
+    # Result codes returned from `insert`. The caller (Rangeable) uses these
+    # to decide whether to bump the container-level version counter.
+    MUTATED    = :mutated
+    IDEMPOTENT = :idempotent
+
+    def initialize
+      @entries = []
+    end
+
+    # Returns a frozen snapshot of the merged intervals as `[[lo, hi], ...]`.
+    # The list satisfies RFC §5.1 (I1).
+    def to_pairs
+      @entries.map(&:to_a)
+    end
+
+    def each(&block)
+      @entries.each(&block)
+    end
+
+    def empty?
+      @entries.empty?
+    end
+
+    def size
+      @entries.size
+    end
+
+    # Insert `[lo, hi]` into the set, performing union-with-merge per RFC §6.1.
+    # Returns `MUTATED` if the canonical state changed (caller should bump
+    # version), `IDEMPOTENT` if the insert was absorbed by an existing entry
+    # (caller MUST NOT bump version, per Test #21 and Lemma 6.5.B).
+    def insert(lo, hi)
+      raise ArgumentError, "lo (#{lo}) > hi (#{hi})" if lo > hi
+
+      # Step 4 of §6.1: bsearch for the leftmost touch candidate.
+      # Predicate: `iv.hi + 1 >= lo`. We use `iv.hi + 1` (not `lo - 1`) to
+      # avoid Integer underflow at lo == Int.min boundaries (§4.7 C5).
+      i0 = @entries.bsearch_index { |iv| iv.hi + 1 >= lo } || @entries.size
+
+      # Step 5: collect contiguous touch entries while `entries[i].lo <= hi + 1`.
+      to_merge_end = i0
+      while to_merge_end < @entries.size && @entries[to_merge_end].lo <= hi + 1
+        to_merge_end += 1
+      end
+      merge_count = to_merge_end - i0
+
+      # Step 6: containment idempotent fast-path. If we touch exactly one
+      # existing entry that fully covers [lo, hi], this insert is a no-op.
+      # MUST NOT mutate, MUST NOT bump version.
+      if merge_count == 1
+        existing = @entries[i0]
+        if existing.lo <= lo && hi <= existing.hi
+          return IDEMPOTENT
+        end
+      end
+
+      # Step 7: real mutation path. Compute merged bounds, splice in.
+      new_lo = lo
+      new_hi = hi
+      if merge_count.positive?
+        first = @entries[i0]
+        last  = @entries[to_merge_end - 1]
+        new_lo = first.lo if first.lo < new_lo
+        new_hi = last.hi  if last.hi  > new_hi
+      end
+      merged = Interval.new(new_lo, new_hi)
+      # `slice!` removes the touched range; then we splice the merged
+      # interval at i0. Equivalent to the §6.1 reference pseudocode but
+      # avoids repeated O(m_e) shifts that delete_at would cause in a loop.
+      @entries.slice!(i0, merge_count) if merge_count.positive?
+      @entries.insert(i0, merged)
+      MUTATED
+    end
+  end
+end

data/lib/rangeable/interval.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class Rangeable
+  # Immutable closed integer interval [lo, hi].
+  #
+  # Used internally as the storage form within Rangeable::DisjointSet. Instances
+  # are produced by `insert` and never mutated; equality is structural so two
+  # intervals with the same `lo` / `hi` compare equal under `==`, `eql?` and
+  # `hash`.
+  class Interval
+    attr_reader :lo, :hi
+
+    def initialize(lo, hi)
+      raise ArgumentError, "lo (#{lo}) > hi (#{hi})" if lo > hi
+
+      @lo = lo
+      @hi = hi
+      freeze
+    end
+
+    # Inclusive containment check: true when `coord` falls inside [lo, hi].
+    def include?(coord)
+      lo <= coord && coord <= hi
+    end
+
+    # Returns the interval as a 2-element array `[lo, hi]`.
+    def to_a
+      [lo, hi]
+    end
+
+    def ==(other)
+      other.is_a?(Interval) && other.lo == lo && other.hi == hi
+    end
+    alias eql? ==
+
+    def hash
+      [Interval, lo, hi].hash
+    end
+
+    def to_s
+      "[#{lo}, #{hi}]"
+    end
+
+    def inspect
+      "#<Rangeable::Interval lo=#{lo} hi=#{hi}>"
+    end
+  end
+end

data/lib/rangeable/slot.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class Rangeable
+  # Thin wrapper returned by `Rangeable#[]`. Wraps the active-element list at
+  # a single coordinate so we can grow the surface (e.g. add `count`,
+  # `transitions`, etc.) without changing the public type.
+  #
+  # `objs` is always a frozen `Array` of elements ordered by first-insert
+  # `ord(e)` ascending (RFC §4.5). We use a `Struct` (rather than a plain
+  # class) because the hot-path call sites are `r[i].objs` and the Struct
+  # accessor is materially faster than going through `attr_reader` + an
+  # ivar in MRI.
+  Slot = Struct.new(:objs) do
+    def empty?
+      objs.empty?
+    end
+
+    def size
+      objs.size
+    end
+    alias_method :count, :size
+    alias_method :length, :size
+
+    def each(&block)
+      objs.each(&block)
+    end
+
+    def to_a
+      objs.dup
+    end
+
+    def inspect
+      "#<Rangeable::Slot objs=#{objs.inspect}>"
+    end
+  end
+end

data/lib/rangeable/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Defined as a class because the main `Rangeable` symbol in `rangeable.rb` is
+# a class. We declare it the same way here so that requiring this file
+# alone (e.g. from the gemspec) does not lock the symbol into being a
+# module.
+class Rangeable
+  VERSION = '1.0.0'
+end

data/lib/rangeable.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative 'rangeable/version'
+require_relative 'rangeable/interval'
+require_relative 'rangeable/slot'
+require_relative 'rangeable/disjoint_set'
+require_relative 'rangeable/boundary_index'
+
+# `Rangeable` is the language-neutral, generic, integer-coordinate closed-
+# interval set container described in `RFC.md`. It pairs hashable elements
+# with their merged disjoint integer ranges and supports three query
+# families: by-element (`get_range`), by-position (`r[i]`) and by-range
+# (`transitions`). See RFC §3 for the API surface.
+class Rangeable
+  # Raised when an interval is malformed (start > end). Subclassing
+  # `ArgumentError` keeps it `rescue`able alongside other invalid-arg
+  # mistakes per RFC §3.7.
+  class InvalidIntervalError < ArgumentError; end
+
+  # `Rangeable::TransitionEvent` is the public alias for the Struct defined
+  # inside the index. Re-exposed here so callers don't need to reach through
+  # `BoundaryIndex` to reference its type.
+  TransitionEvent = ::Rangeable::BoundaryIndex::TransitionEvent unless const_defined?(:TransitionEvent, false)
+
+  # Frozen empty Array we hand back from `[]` when the coordinate is
+  # outside every segment. Avoids re-allocating an empty Array per query.
+  EMPTY_ACTIVE = [].freeze unless const_defined?(:EMPTY_ACTIVE, false)
+
+  attr_reader :version
+
+  # Build a fresh empty container. RFC §3.1.
+  def initialize
+    @intervals       = {}     # element => DisjointSet
+    @insertion_order = []     # Array<element> in first-insert order
+    @ord             = {}     # element => Integer (1-based)
+    @version         = 0
+    @event_index     = nil    # BoundaryIndex or nil (lazy)
+  end
+
+  # Sugar: `Rangeable.empty` matches the RFC §3.1 alias.
+  def self.empty
+    new
+  end
+
+  # Insert `element` covering `[start, end_]` (closed interval). Idempotent
+  # by RFC §3.2: re-inserting a sub-range that is already fully contained
+  # leaves the container unchanged and does NOT bump version.
+  #
+  # The RFC reference uses the keyword `end:`, but Ruby treats `end` inside
+  # method headers as a soft-keyword that is fine in keyword-arg position.
+  # We accept it that way to match the RFC API exactly.
+  def insert(element, start:, end:)
+    end_ = binding.local_variable_get(:end)
+    raise InvalidIntervalError, "start (#{start}) > end (#{end_})" if start > end_
+
+    e = freeze_for_insert(element)
+
+    set = @intervals[e]
+    if set.nil?
+      set = DisjointSet.new
+      @intervals[e] = set
+      @insertion_order << e
+      @ord[e] = @insertion_order.length
+    end
+
+    result = set.insert(start, end_)
+    if result == DisjointSet::MUTATED
+      @version += 1
+      @event_index = nil
+    end
+    self
+  end
+
+  # Active-element list at `i`. RFC §3.3.
+  # O(log |segments| + r) once the index is built.
+  #
+  # Hot path: we inline the segment bsearch here (instead of going through
+  # a private helper or method dispatch into BoundaryIndex#segment_at) so
+  # `r[i]` stays allocation-free apart from the unavoidable `Slot`
+  # envelope. The cached active array on the segment is already frozen,
+  # so `Slot.new` does not duplicate it (see `Slot#initialize`).
+  def [](i)
+    ensure_event_index_fresh
+    segs = @event_index.segments
+    idx = segs.bsearch_index { |seg| seg.hi >= i }
+    if idx
+      seg = segs[idx]
+      if seg.lo <= i
+        Slot.new(seg.active)
+      else
+        Slot.new(EMPTY_ACTIVE)
+      end
+    else
+      Slot.new(EMPTY_ACTIVE)
+    end
+  end
+  alias active_at_index []
+
+  # Same as `[]` but spelled out to match RFC §3.3.
+  def active_at(index:)
+    self[index]
+  end
+
+  # Merged ranges for `element` as `[[lo, hi], ...]`. RFC §3.4. Returns an
+  # empty Array when the element has never been inserted.
+  def get_range(element)
+    set = @intervals[element]
+    return [] unless set
+
+    set.to_pairs
+  end
+  alias range_of get_range
+  alias get_range_of get_range
+
+  # Transitions (open / close events) within an inclusive coordinate range.
+  # Accepts a Ruby `Range` (inclusive or exclusive). RFC §3.5.
+  def transitions(over:)
+    raise InvalidIntervalError, "transitions range must be a Range" unless over.is_a?(Range)
+
+    lo = over.begin
+    hi = over.end
+    raise InvalidIntervalError, "open-ended begin not supported" if lo.nil?
+
+    # Normalise exclusive end (`a...b` ⇒ inclusive end `b - 1`).
+    hi = hi - 1 if !hi.nil? && over.exclude_end?
+
+    # Open-ended top (`a..nil`) means +∞ ⇒ include all events.
+    if hi.nil?
+      raise InvalidIntervalError, "lo (#{lo}) > hi (nil)" if lo.nil?
+    else
+      raise InvalidIntervalError, "lo (#{lo}) > hi (#{hi})" if lo > hi
+    end
+
+    ensure_event_index_fresh
+    upper = hi.nil? ? nil : hi + 1
+    @event_index.events_in_range(lo, upper).map do |ev|
+      TransitionEvent.new(ev.coordinate, ev.kind, ev.element, ev.ord)
+    end
+  end
+
+  # Number of distinct equivalence-class elements ever inserted. RFC §3.5.1.
+  def count
+    @insertion_order.length
+  end
+  alias size count
+  alias length count
+
+  # `count == 0`. RFC §3.5.1.
+  def empty?
+    @insertion_order.empty?
+  end
+
+  # Iterate `(element, ranges)` pairs in insertion-order ascending. RFC §3.5.1.
+  def each(&block)
+    return enum_for(:each) unless block_given?
+
+    @insertion_order.each do |element|
+      yield element, @intervals[element].to_pairs
+    end
+    self
+  end
+  include Enumerable
+
+  # Deep copy of the entire container per RFC §3.5.1. Mutation on the copy
+  # MUST NOT affect this instance and vice versa.
+  def copy
+    dup_instance = self.class.new
+    @insertion_order.each do |element|
+      dup_instance.send(:replant, element, @intervals[element], @ord[element])
+    end
+    dup_instance.send(:set_version_after_copy, @version)
+    dup_instance
+  end
+  alias dup copy
+  alias clone copy
+
+  # Sugar form: `Rangeable.range_of(element, from: r)`. RFC §3.4.
+  def self.range_of(element, from:)
+    from.get_range(element)
+  end
+
+  # Refinement-only sugar so `element.get_range(from: r)` works without
+  # polluting the global Object namespace. Caller does `using Rangeable::Refinements`.
+  module Refinements
+    refine Object do
+      def get_range(from:)
+        from.get_range(self)
+      end
+    end
+  end
+
+  private
+
+  # RFC §4.6 (M2): freeze on insert as cheap defence against caller-side
+  # mutation of hash-affecting state. We try to dup-then-freeze; if `dup`
+  # is not supported (some Symbol-like cases) we fall back to the original.
+  def freeze_for_insert(element)
+    return element if element.frozen?
+
+    begin
+      element.dup.freeze
+    rescue TypeError
+      element
+    end
+  end
+
+  def ensure_event_index_fresh
+    return if @event_index && @event_index.version == @version
+
+    # Snapshot the version at the start of the build. After build, recheck
+    # against `@version` (T3 mutex pattern, §11). In Ruby's GVL world this
+    # is mostly a no-op, but the comment exists to flag the contract for
+    # any future Ractor port.
+    v_start = @version
+    rebuilt = BoundaryIndex.build(@intervals, @ord, v_start)
+    @event_index = rebuilt if @version == v_start
+  end
+
+  # Public-ish helper kept available for direct callers. The hot path in
+  # `[]` inlines this for one less method dispatch per query.
+  def active_at_coord(coord)
+    ensure_event_index_fresh
+    seg = @event_index.segment_at(coord)
+    seg ? seg.active : EMPTY_ACTIVE
+  end
+
+  # Used by `copy` to clone an element's interval set with its ord intact.
+  # Lives here as a private setter so the public surface stays clean.
+  def replant(element, source_set, source_ord)
+    new_set = DisjointSet.new
+    source_set.each do |iv|
+      # MUTATED is the only outcome for sequential insertions of disjoint,
+      # ordered intervals into an empty set; we don't need to inspect the
+      # return value but we still call insert to keep all invariants in
+      # one place.
+      new_set.insert(iv.lo, iv.hi)
+    end
+    @intervals[element] = new_set
+    @insertion_order << element
+    @ord[element] = source_ord
+  end
+
+  def set_version_after_copy(v)
+    @version = v
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: rangeable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ZhgChgLi
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  Rangeable is a language-neutral, generic, integer-coordinate closed-interval
+  set container. It pairs hashable elements with their merged disjoint integer
+  ranges and answers three queries: by-element ranges, by-position active set,
+  and by-range transition events. The Ruby reference implementation follows
+  the Rangeable RFC normatively, including idempotent containment fast-path,
+  lazy boundary-event indexing, and first-insert deterministic ordering.
+email:
+- zhgchgli@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/rangeable.rb
+- lib/rangeable/boundary_index.rb
+- lib/rangeable/disjoint_set.rb
+- lib/rangeable/interval.rb
+- lib/rangeable/slot.rb
+- lib/rangeable/version.rb
+homepage: https://github.com/ZhgChgLi/RubyRangeable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ZhgChgLi/RubyRangeable
+  source_code_uri: https://github.com/ZhgChgLi/RubyRangeable
+  bug_tracker_uri: https://github.com/ZhgChgLi/RubyRangeable/issues
+  changelog_uri: https://github.com/ZhgChgLi/RubyRangeable/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/ZhgChgLi/RangeableRFC/blob/main/RFC.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Hashable-element interval set with first-insert ordered active queries.
+test_files: []