ibex-runtime 0.2.0

data/lib/ibex/runtime.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "runtime/version"
+require_relative "runtime/table_format"
+require_relative "tables/compact"
+require_relative "tables/compact_actions"
+require_relative "tables/compact_productions"
+require_relative "runtime/event_sanitizer"
+require_relative "runtime/event"
+require_relative "runtime/observation"
+require_relative "runtime/cst"
+require_relative "runtime/ast_data"
+require_relative "runtime/resource_limits"
+require_relative "runtime/repair"
+require_relative "runtime/repair_priority_queue"
+require_relative "runtime/repair_search"
+require_relative "runtime/parser_sync_recovery"
+require_relative "runtime/parser"
+require_relative "runtime/lexer_input"
+require_relative "runtime/generated_lexer"
+require_relative "runtime/jsonl_tracer"
+require_relative "runtime/event_jsonl_tracer"
+
+module Ibex
+  module Runtime
+  end
+end

data/lib/ibex/tables/compact.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Tables
+    # Encodes nonnegative integer arrays into compact generated-source
+    # literals. Zero represents nil; positive values are offset by one.
+    module PackedIntegers
+      module_function
+
+      # @rbs (Array[Integer?] values) -> String
+      def encode(values)
+        encoded = values.map do |value|
+          raise ArgumentError, "packed integer must be nonnegative or nil" if value&.negative?
+
+          value ? value + 1 : 0
+        end.pack("w*")
+        [encoded].pack("m0")
+      end
+
+      # @rbs (String source) -> Array[Integer?]
+      def decode(source)
+        binary = source.unpack1("m0")
+        raise ArgumentError, "packed integer source is invalid" unless binary.is_a?(String)
+
+        values = binary.unpack("w*") #: Array[Integer]
+        values.map { |value| value.zero? ? nil : value - 1 }
+      rescue ArgumentError
+        raise ArgumentError, "packed integer source is invalid"
+      end
+
+      # @rbs (String source) -> Array[Integer]
+      def decode_required(source)
+        decode(source).map do |value|
+          raise ArgumentError, "packed integer source contains nil" unless value
+
+          value
+        end
+      end
+
+      # Zigzag-encode signed values after reserving zero for nil.
+      # @rbs (Array[Integer?] values) -> String
+      def encode_signed(values)
+        encode(
+          values.map do |value|
+            next unless value
+
+            value.negative? ? (-value * 2) - 1 : value * 2
+          end
+        )
+      end
+
+      # @rbs (String source) -> Array[Integer?]
+      def decode_signed(source)
+        decode(source).map do |value|
+          next unless value
+
+          value.even? ? value / 2 : -((value + 1) / 2)
+        end
+      end
+    end
+
+    # Sparse table represented by per-row offsets and ownership checks.
+    class Compact
+      DENSE_CELL_LIMIT = 1_000_000 #: Integer
+
+      attr_reader :offsets #: Array[Integer]
+      attr_reader :values #: Array[untyped]
+      attr_reader :checks #: Array[Integer?]
+      attr_reader :row_count #: Integer
+      attr_reader :dense_values #: Array[untyped]?
+      attr_reader :dense_width #: Integer?
+
+      class << self
+        # @rbs (Array[Hash[Integer, untyped]] rows, ?dense: bool) -> Compact
+        def build(rows, dense: true)
+          offsets = Array.new(rows.length, 0)
+          values = [] #: Array[untyped]
+          checks = [] #: Array[Integer?]
+          next_offsets = {} #: Hash[Array[Integer], Integer]
+          rows.each_index.sort_by { |row| [-rows[row].length, row] }.each do |row|
+            offset = find_offset(rows[row].keys, checks, next_offsets)
+            offsets[row] = offset
+            rows[row].each do |column, value|
+              index = offset + column
+              values[index] = value
+              checks[index] = row
+            end
+          end
+          dense_width = rows.flat_map(&:keys).max.to_i + 1 if dense
+          dense_width = nil if dense_width && (rows.length * dense_width) > DENSE_CELL_LIMIT
+          new(
+            offsets: offsets, values: values, checks: checks, row_count: rows.length,
+            dense_width: dense_width
+          )
+        end
+
+        # @rbs (String offsets, String values, String checks, row_count: Integer,
+        #   ?dense_width: Integer?) -> Compact
+        def packed(offsets, values, checks, row_count:, dense_width: nil)
+          new(
+            offsets: PackedIntegers.decode_required(offsets),
+            values: PackedIntegers.decode(values),
+            checks: PackedIntegers.decode(checks),
+            row_count: row_count,
+            dense_width: dense_width
+          )
+        end
+
+        private
+
+        # @rbs (Array[Integer] columns, Array[Integer?] checks, Hash[Array[Integer], Integer] next_offsets) -> Integer
+        def find_offset(columns, checks, next_offsets)
+          return 0 if columns.empty?
+
+          signature = columns.sort
+          offset = next_offsets.fetch(signature, 0)
+          offset += 1 while columns.any? { |column| checks[offset + column] }
+          next_offsets[signature] = offset + 1
+          offset
+        end
+      end
+
+      # @rbs (offsets: Array[Integer], values: Array[untyped], checks: Array[Integer?],
+      #   row_count: Integer, ?dense_width: Integer?) -> void
+      def initialize(offsets:, values:, checks:, row_count:, dense_width: nil)
+        @offsets = offsets.freeze
+        @values = values.freeze
+        @checks = checks.freeze
+        @row_count = row_count
+        @dense_width = dense_width
+        @dense_values = dense_layout(dense_width)
+        freeze
+      end
+
+      # Keep predicate dispatch out of this lookup because every parser action
+      # and goto crosses it.
+      # rubocop:disable Style/NumericPredicate
+      # @rbs (Integer row, Integer column) -> untyped
+      def lookup(row, column)
+        return nil if row < 0 || row >= @row_count || column < 0
+
+        index = @offsets[row] + column
+        return nil if index < 0 || index >= @checks.length
+
+        @checks[index] == row ? @values[index] : nil
+      end
+      # rubocop:enable Style/NumericPredicate
+
+      # @rbs (Integer row) -> Hash[Integer, untyped]
+      def row(row)
+        return {} unless row.between?(0, @row_count - 1)
+
+        result = {} #: Hash[Integer, untyped]
+        @checks.each_index do |index|
+          next unless @checks[index] == row
+
+          result[index - @offsets[row]] = @values[index]
+        end
+        result
+      end
+
+      private
+
+      # @rbs (Integer? dense_width) -> Array[untyped]?
+      def dense_layout(dense_width)
+        return nil unless dense_width
+        raise ArgumentError, "compact dense width must be positive" unless dense_width.positive?
+        return nil if (@row_count * dense_width) > DENSE_CELL_LIMIT
+
+        dense = Array.new(@row_count * dense_width) #: Array[untyped]
+        @checks.each_index do |index|
+          row = @checks[index]
+          next unless row
+
+          column = index - @offsets.fetch(row)
+          raise ArgumentError, "compact column exceeds the dense row width" unless
+            column.between?(0, dense_width - 1)
+
+          dense[(row * dense_width) + column] = @values[index]
+        end
+        dense.freeze
+      end
+    end
+  end
+end

data/lib/ibex/tables/compact_actions.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "compact" unless defined?(Ibex::Tables::Compact)
+
+module Ibex
+  module Tables
+    # Compact action table with an integer-coded hot representation and a
+    # compatible decoded lookup surface for the generic runtime.
+    class CompactActions < Compact
+      ACCEPT_CODE = 0 #: Integer
+      ERROR_CODE = -1 #: Integer
+      SHIFT_BASE = 1 #: Integer
+      REDUCE_BASE = -2 #: Integer
+      LEGACY_ERROR_CODE = 1 #: Integer
+      LEGACY_SHIFT_BASE = 2 #: Integer
+      LEGACY_REDUCE_BASE = 3 #: Integer
+      private_constant :LEGACY_ERROR_CODE, :LEGACY_SHIFT_BASE, :LEGACY_REDUCE_BASE
+
+      attr_reader :codes #: Array[Integer?]
+      attr_reader :dense_codes #: Array[Integer?]?
+      attr_reader :column_count #: Integer?
+
+      class << self
+        # @rbs (Array[Hash[Integer, untyped]] rows) -> CompactActions
+        def build(rows)
+          packed_rows = rows.map do |row|
+            row.transform_values { |action| pack(action) }
+          end
+          layout = Compact.build(packed_rows, dense: false)
+          column_count = rows.flat_map(&:keys).max.to_i + 1
+          column_count = nil if (rows.length * column_count) > Compact::DENSE_CELL_LIMIT
+          new(
+            offsets: layout.offsets,
+            codes: layout.values,
+            checks: layout.checks,
+            row_count: layout.row_count,
+            encoding: :signed,
+            column_count: column_count
+          )
+        end
+
+        # @rbs (String offsets, String codes, String checks, row_count: Integer,
+        #   ?encoding: Symbol, ?column_count: Integer?) -> CompactActions
+        def packed(offsets, codes, checks, row_count:, encoding: :legacy, column_count: nil)
+          new(
+            offsets: PackedIntegers.decode_required(offsets),
+            codes: encoding == :signed ? PackedIntegers.decode_signed(codes) : PackedIntegers.decode(codes),
+            checks: PackedIntegers.decode(checks),
+            row_count: row_count,
+            encoding: encoding,
+            column_count: column_count
+          )
+        end
+
+        # @rbs (untyped action) -> Integer?
+        def pack(action)
+          return unless action
+
+          case action.fetch(0)
+          when :accept then ACCEPT_CODE
+          when :error then ERROR_CODE
+          when :shift then SHIFT_BASE + action.fetch(1)
+          when :reduce then REDUCE_BASE - action.fetch(1)
+          else raise ArgumentError, "unknown compact parser action #{action.inspect}"
+          end
+        end
+
+        # @rbs (Integer? code) -> untyped
+        def unpack(code)
+          return unless code
+          return [:accept].freeze if code == ACCEPT_CODE
+          return [:error].freeze if code == ERROR_CODE
+          return [:shift, code - SHIFT_BASE].freeze if code.positive?
+
+          [:reduce, REDUCE_BASE - code].freeze
+        end
+
+        # Convert codes emitted before signed compact actions without changing
+        # their generated table literals.
+        # @rbs (Integer? code) -> Integer?
+        def legacy_to_signed(code)
+          return unless code
+          return ACCEPT_CODE if code == ACCEPT_CODE
+          return ERROR_CODE if code == LEGACY_ERROR_CODE
+          return SHIFT_BASE + ((code - LEGACY_SHIFT_BASE) / 2) if code.even?
+
+          REDUCE_BASE - ((code - LEGACY_REDUCE_BASE) / 2)
+        end
+      end
+
+      # @rbs (offsets: Array[Integer], codes: Array[Integer?], checks: Array[Integer?],
+      #   row_count: Integer, ?encoding: Symbol, ?column_count: Integer?) -> void
+      def initialize(offsets:, codes:, checks:, row_count:, encoding: :legacy, column_count: nil)
+        codes = codes.map { |code| self.class.legacy_to_signed(code) } if encoding == :legacy
+        unless %i[legacy signed].include?(encoding)
+          raise ArgumentError, "unknown compact action encoding #{encoding.inspect}"
+        end
+
+        @codes = codes.freeze
+        @column_count = column_count
+        @dense_codes = dense_action_layout(offsets, codes, checks, row_count, column_count)
+        decoded_cache = {} #: Hash[Integer, untyped]
+        decoded = codes.map do |code|
+          code.nil? ? nil : decoded_cache[code] ||= self.class.unpack(code)
+        end
+        super(offsets: offsets, values: decoded, checks: checks, row_count: row_count)
+      end
+
+      private
+
+      # @rbs (Array[Integer] offsets, Array[Integer?] codes, Array[Integer?] checks,
+      #   Integer row_count, Integer? column_count) -> Array[Integer?]?
+      def dense_action_layout(offsets, codes, checks, row_count, column_count)
+        return nil unless column_count
+        raise ArgumentError, "compact action column count must be positive" unless column_count.positive?
+
+        return nil if (row_count * column_count) > Compact::DENSE_CELL_LIMIT
+
+        dense = Array.new(row_count * column_count) #: Array[Integer?]
+        checks.each_index do |index|
+          row = checks[index]
+          next unless row
+
+          column = index - offsets.fetch(row)
+          raise ArgumentError, "compact action column exceeds the dense row width" unless
+            column.between?(0, column_count - 1)
+
+          dense[(row * column_count) + column] = codes[index]
+        end
+        dense.freeze
+      end
+    end
+  end
+end

data/lib/ibex/tables/compact_productions.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Tables
+    # Production metadata with parallel primitive arrays for the direct parser
+    # and a compatible Array-of-Hash surface for generic runtime consumers.
+    class CompactProductions < Array #[Hash[Symbol, untyped]]
+      VALUES_ACTION = 1 #: Integer
+      BORROWED_VALUES_ACTION = 2 #: Integer
+      LOCATION_ACTION = 4 #: Integer
+      COMPOSITION_ACTION = 8 #: Integer
+      POSITIONAL_ACTION = 16 #: Integer
+      VALID_FLAGS = VALUES_ACTION | BORROWED_VALUES_ACTION | LOCATION_ACTION |
+                    COMPOSITION_ACTION | POSITIONAL_ACTION #: Integer
+      CORE_FIELDS = %i[
+        lhs length action values_action borrowed_values_action location_action composition_action
+      ].freeze #: Array[Symbol]
+      private_constant :VALID_FLAGS, :CORE_FIELDS
+
+      attr_reader :lhs_ids #: Array[Integer]
+      attr_reader :lengths #: Array[Integer]
+      attr_reader :actions #: Array[Symbol?]
+      attr_reader :flags #: Array[Integer]
+
+      class << self
+        # @rbs (Array[Hash[Symbol, untyped]] productions) -> CompactProductions
+        def build(productions)
+          lhs_ids = [] #: Array[Integer]
+          lengths = [] #: Array[Integer]
+          actions = [] #: Array[Symbol?]
+          flags = [] #: Array[Integer]
+          metadata = {} #: Hash[Integer, Hash[Symbol, untyped]]
+          productions.each_with_index do |production, index|
+            lhs_ids << production.fetch(:lhs)
+            lengths << production.fetch(:length)
+            actions << production[:action]
+            flags << flags_for(production)
+            extra = production.except(
+              :lhs, :length, :action, :values_action, :borrowed_values_action, :location_action, :composition_action
+            )
+            metadata[index] = extra unless extra.empty?
+          end
+          new(lhs_ids: lhs_ids, lengths: lengths, actions: actions, flags: flags, metadata: metadata)
+        end
+
+        # @rbs (String lhs_ids, String lengths, String flags,
+        #   ?metadata: Hash[Integer, Hash[Symbol, untyped]]) -> CompactProductions
+        def packed(lhs_ids, lengths, flags, metadata: {})
+          decoded_flags = PackedIntegers.decode_required(flags)
+          actions = decoded_flags.each_index.map do |index|
+            :"_ibex_action_#{index}" unless decoded_flags[index].zero?
+          end
+          new(
+            lhs_ids: PackedIntegers.decode_required(lhs_ids),
+            lengths: PackedIntegers.decode_required(lengths),
+            actions: actions,
+            flags: decoded_flags,
+            metadata: metadata
+          )
+        end
+
+        private
+
+        # @rbs (Hash[Symbol, untyped] production) -> Integer
+        def flags_for(production)
+          value = 0
+          value |= VALUES_ACTION if production[:values_action] == true
+          value |= BORROWED_VALUES_ACTION if production[:borrowed_values_action] == true
+          value |= LOCATION_ACTION if production[:location_action] == true
+          value |= COMPOSITION_ACTION if production[:composition_action] == true
+          value
+        end
+      end
+
+      # @rbs (lhs_ids: Array[Integer], lengths: Array[Integer], actions: Array[Symbol?],
+      #   flags: Array[Integer], ?metadata: Hash[Integer, Hash[Symbol, untyped]]) -> void
+      def initialize(lhs_ids:, lengths:, actions:, flags:, metadata: {})
+        size = lhs_ids.length
+        unless lengths.length == size && actions.length == size && flags.length == size
+          raise ArgumentError, "compact production arrays must have the same length"
+        end
+
+        @lhs_ids = lhs_ids.map { |value| nonnegative_integer!(value, "lhs") }.freeze
+        @lengths = lengths.map { |value| nonnegative_integer!(value, "length") }.freeze
+        @actions = actions.map { |value| action!(value) }.freeze
+        @flags = flags.map { |value| flags!(value) }.freeze
+        validate_markers!
+        validate_metadata!(metadata, size)
+        super(Array.new(size) { |index| decode(index, metadata[index]) })
+        freeze
+      end
+
+      # @rbs () -> bool
+      def direct_values?
+        @direct_values
+      end
+
+      private
+
+      # @rbs (untyped value, String name) -> Integer
+      def nonnegative_integer!(value, name)
+        return value if value.is_a?(Integer) && !value.negative?
+
+        raise ArgumentError, "compact production #{name} must be a nonnegative Integer"
+      end
+
+      # @rbs (untyped value) -> Symbol?
+      def action!(value)
+        return value if value.nil? || value.is_a?(Symbol)
+
+        raise ArgumentError, "compact production action must be a Symbol or nil"
+      end
+
+      # @rbs (untyped value) -> Integer
+      def flags!(value)
+        return value if value.is_a?(Integer) && !value.negative? && value.nobits?(~VALID_FLAGS)
+
+        raise ArgumentError, "compact production flags are invalid"
+      end
+
+      # @rbs () -> void
+      def validate_markers!
+        @flags.each_with_index do |value, index|
+          borrowed = value.anybits?(BORROWED_VALUES_ACTION)
+          values = value.anybits?(VALUES_ACTION)
+          positional = value.anybits?(POSITIONAL_ACTION)
+          raise ArgumentError, "borrowed production #{index} must be a values action" if borrowed && !values
+          if positional && value.anybits?(VALUES_ACTION | LOCATION_ACTION | COMPOSITION_ACTION)
+            raise ArgumentError, "positional production #{index} cannot combine action ABI flags"
+          end
+        end
+        @direct_values = @actions.each_index.all? do |index|
+          @actions[index].nil? || @flags[index].anybits?(VALUES_ACTION | POSITIONAL_ACTION)
+        end
+      end
+
+      # @rbs (Hash[Integer, Hash[Symbol, untyped]] metadata, Integer size) -> void
+      def validate_metadata!(metadata, size)
+        metadata.each do |index, entry|
+          unless index.is_a?(Integer) && index.between?(0, size - 1) && entry.is_a?(Hash)
+            raise ArgumentError, "compact production metadata is invalid"
+          end
+          if entry.keys.any? { |key| CORE_FIELDS.include?(key) }
+            raise ArgumentError, "compact production metadata cannot replace core fields"
+          end
+        end
+      end
+
+      # @rbs (Integer index, Hash[Symbol, untyped]? metadata) -> Hash[Symbol, untyped]
+      def decode(index, metadata)
+        entry = {} #: Hash[Symbol, untyped]
+        entry[:lhs] = @lhs_ids[index]
+        entry[:length] = @lengths[index]
+        entry[:action] = @actions[index]
+        value = @flags[index]
+        entry[:values_action] = true if value.anybits?(VALUES_ACTION)
+        entry[:borrowed_values_action] = true if value.anybits?(BORROWED_VALUES_ACTION)
+        entry[:location_action] = true if value.anybits?(LOCATION_ACTION)
+        entry[:composition_action] = true if value.anybits?(COMPOSITION_ACTION)
+        entry[:positional_action] = true if value.anybits?(POSITIONAL_ACTION)
+        entry.merge!(metadata) if metadata
+        entry.freeze
+      end
+    end
+  end
+end

data/sig/ibex/runtime/ast_data.rbs

@@ -0,0 +1,12 @@
+# Generated from lib/ibex/runtime/ast_data.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    # Builds Data classes on Ruby 3.2+ and an immutable Struct-compatible
+    # fallback on older supported Rubies.
+    module ASTData
+      # @rbs (*Symbol members) -> singleton(Object)
+      def self?.define: (*Symbol members) -> singleton(Object)
+    end
+  end
+end

data/sig/ibex/runtime/cst/annotation.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/ibex/runtime/cst/annotation.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    module CST
+      # Opaque identity used to track a syntax occurrence across path-copying edits.
+      class SyntaxAnnotation
+        # @rbs () -> void
+        def initialize: () -> void
+      end
+    end
+  end
+end

data/sig/ibex/runtime/cst/cursor.rbs

@@ -0,0 +1,34 @@
+# Generated from lib/ibex/runtime/cst/cursor.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    module CST
+      # Allocation-light cursor over Green elements and absolute offsets.
+      # rubocop:disable Naming/PredicateMethod -- cursor movement names follow the public tree-cursor convention.
+      class Cursor
+        type green = GreenNode | GreenToken
+
+        type frame = [ GreenNode, Integer, Integer ]
+
+        attr_reader green: green
+
+        attr_reader offset: Integer
+
+        # @rbs (SyntaxNode node) -> void
+        def initialize: (SyntaxNode node) -> void
+
+        # @rbs () -> bool
+        def goto_first_child: () -> bool
+
+        # @rbs () -> bool
+        def goto_next_sibling: () -> bool
+
+        # @rbs () -> bool
+        def goto_parent: () -> bool
+
+        # @rbs () -> Integer
+        def kind: () -> Integer
+      end
+    end
+  end
+end

data/sig/ibex/runtime/cst/diff.rbs

@@ -0,0 +1,29 @@
+# Generated from lib/ibex/runtime/cst/diff.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    module CST
+      # Computes byte edits while skipping physically shared Green subtrees.
+      module Diff
+        # @rbs (SyntaxNode old_root, SyntaxNode new_root) -> Array[TextEdit]
+        def self?.text_edits: (SyntaxNode old_root, SyntaxNode new_root) -> Array[TextEdit]
+
+        # @rbs (GreenNode | GreenToken old_green, GreenNode | GreenToken new_green,
+        #   Integer offset, Array[TextEdit] edits) -> void
+        def self?.compare: (GreenNode | GreenToken old_green, GreenNode | GreenToken new_green, Integer offset, Array[TextEdit] edits) -> void
+
+        # @rbs (GreenNode | GreenToken left, GreenNode | GreenToken right) -> bool
+        def self?.compatible_nodes?: (GreenNode | GreenToken left, GreenNode | GreenToken right) -> bool
+
+        # @rbs (String old_text, String new_text, Integer offset, Array[TextEdit] edits) -> void
+        def self?.append_trimmed_edit: (String old_text, String new_text, Integer offset, Array[TextEdit] edits) -> void
+
+        # @rbs (String left, String right) -> Integer
+        def self?.common_prefix: (String left, String right) -> Integer
+
+        # @rbs (String left, String right, Integer prefix) -> Integer
+        def self?.common_suffix: (String left, String right, Integer prefix) -> Integer
+      end
+    end
+  end
+end

data/sig/ibex/runtime/cst/editing.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/ibex/runtime/cst/editing.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    module CST
+      # Shared path-copying operations for Red syntax elements.
+      module Editing
+        type element = SyntaxNode | SyntaxToken
+
+        type green = GreenNode | GreenToken
+
+        # @rbs (element target, green | element replacement) -> SyntaxNode
+        def self?.replace: (element target, green | element replacement) -> SyntaxNode
+
+        # @rbs (SyntaxNode previous, GreenNode green) -> SyntaxNode
+        def self?.red_root: (SyntaxNode previous, GreenNode green) -> SyntaxNode
+
+        # @rbs (green | element value) -> green
+        def self?.green_element: (green | element value) -> green
+      end
+    end
+  end
+end

data/sig/ibex/runtime/cst/editor.rbs

@@ -0,0 +1,43 @@
+# Generated from lib/ibex/runtime/cst/editor.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    module CST
+      class EditConflictError < StandardError
+      end
+
+      # Applies multiple occurrence-addressed replacements in one path-copying pass.
+      class SyntaxEditor
+        type element = SyntaxNode | SyntaxToken
+
+        type green = GreenNode | GreenToken
+
+        type edit = [ element, green ]
+
+        @root: SyntaxNode
+
+        @edits: Array[edit]
+
+        # @rbs (SyntaxNode root) -> void
+        def initialize: (SyntaxNode root) -> void
+
+        # @rbs (element target, green | element replacement) -> self
+        def replace: (element target, green | element replacement) -> self
+
+        # @rbs () -> SyntaxNode
+        def apply: () -> SyntaxNode
+
+        private
+
+        # @rbs (element element) -> green
+        def apply_element: (element element) -> green
+
+        # @rbs (element possible_ancestor, element element) -> bool
+        def ancestor?: (element possible_ancestor, element element) -> bool
+
+        # @rbs (element left, element right) -> bool
+        def same_occurrence?: (element left, element right) -> bool
+      end
+    end
+  end
+end