expressir 2.4.2 → 2.4.4

data/lib/expressir/express/parser.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+require "json"
 require "parsanol"
 
 module Expressir
@@ -46,10 +48,22 @@ module Expressir
       # @param skip_references [Boolean] skip resolving references
       # @param include_source [Boolean] attach original source code to model elements
       # @param use_native [Boolean] use native parser (default: true when available)
+      # @param use_core [Boolean] use the Rust core parse path
+      #   (default: true when the expressir-core extension is available;
+      #   produces a byte-identical model to the Ruby path — see
+      #   parser_core_parity_spec)
       # @return [Model::ExpFile] ExpFile containing parsed schemas
       # @raise [Error::SchemaParseFailure] if the schema file fails to parse
       def self.from_file(file, skip_references: nil, include_source: nil,
-                         root_path: nil, use_native: nil) # rubocop:disable Metrics/AbcSize
+                         root_path: nil, use_native: nil,
+                         use_core: nil) # rubocop:disable Metrics/AbcSize
+        use_core = Core::NATIVE_AVAILABLE if use_core.nil?
+        if use_core && Core::NATIVE_AVAILABLE
+          return from_file_core(file, skip_references: skip_references,
+                                      include_source: include_source,
+                                      root_path: root_path)
+        end
+
         Expressir::Benchmark.measure_file(file) do
           source = strip_bom(File.read(file))
 
@@ -100,8 +114,32 @@ module Expressir
       # @yield [filename, schemas, error] Optional block called for each file
       # @return [Model::Repository] Repository containing all parsed ExpFiles
       def self.from_files(files, skip_references: nil, include_source: nil,
-root_path: nil, use_native: nil, max_processes: nil, &progress)
-        all_exp_files = if ParallelFiles.sequential?(files, max_processes)
+                          root_path: nil, use_native: nil, max_processes: nil,
+                          compiled_set: nil, &progress)
+        set_path = compiled_set || ENV.fetch("EXPRESSIR_COMPILED_SET", nil)
+        if set_path && core_set_available?
+          repo = from_compiled_set(set_path, files,
+                                   skip_references: skip_references,
+                                   include_source: include_source,
+                                   root_path: root_path)
+          return repo if repo
+        end
+
+        # EXPRESSIR_BATCH=0 escapes the native batch workers: their
+        # Rust threads crash the process under some loads (SIGILL in
+        # the mpmc recv park — see GH batch-crash report); sequential
+        # parsing is slower but proven stable.
+        batch_disabled = ENV["EXPRESSIR_BATCH"] == "0"
+        all_exp_files = if batch_available? && !batch_disabled && files.size > 1
+                          from_files_batch(
+                            files, include_source: include_source,
+                                   root_path: root_path,
+                                   max_processes: max_processes,
+                                   compiled_set_out: set_path
+                          ) do |file, exp_file, error|
+                            progress&.call(file, exp_file&.schemas, error)
+                          end
+                        elsif ParallelFiles.sequential?(files, max_processes)
                           parse_files_sequentially(
                             files, skip_references: skip_references, include_source: include_source,
                                    root_path: root_path, use_native: use_native
@@ -121,8 +159,208 @@ root_path: nil, use_native: nil, max_processes: nil, &progress)
                           end
                         end
 
-        build_repository(all_exp_files, skip_references: skip_references)
+        repository = build_repository(all_exp_files, skip_references: skip_references)
+        if set_path && !skip_references && File.exist?(set_path)
+          files = all_exp_files.compact
+          RefsOverlay.write(set_path, files)
+          graph = Model::Indexes::ItemGraph.new(repository)
+          repository.item_graph = graph
+          require "json"
+          File.write("#{set_path}.graph.json", JSON.generate(graph.tables))
+        end
+
+        repository
+      end
+
+      # Core path: the Rust extension parses and emits the model hash
+      # directly (lutaml wire shape); Ruby hydrates, then remark
+      # attachment runs on the source as usual.
+      def self.from_file_core(file, skip_references: nil,
+                              include_source: nil, root_path: nil, &block)
+        unless Core::NATIVE_AVAILABLE
+          raise Error::StreamingUnsupportedError,
+                "core parse requires the native extension"
+        end
+
+        Expressir::Benchmark.measure_file(file) do
+          source = strip_bom(File.read(file))
+          schema_file = root_path ? Pathname.new(file.to_s).relative_path_from(root_path).to_s : file.to_s
+
+          exp_file =
+            begin
+              Core.parse_to_model(source, schema_file).tap(&:wire_parents)
+            rescue NotImplementedError
+              begin
+                Model::ExpFile.from_hash(
+                  Core.parse_to_model_hash(source, schema_file),
+                )&.tap(&:wire_parents)
+              rescue StandardError => e
+                raise Error::SchemaParseFailure.new(schema_file, e)
+              end
+            rescue StandardError => e
+              raise Error::SchemaParseFailure.new(schema_file, e)
+            end
+
+          finalize_loaded_file(exp_file, source, schema_file,
+                               include_source: include_source)
+
+          unless skip_references
+            Expressir::Benchmark.measure_references do
+              ResolveReferencesModelVisitor.new.visit(exp_file)
+            end
+          end
+
+          exp_file
+        end
+      end
+      private_class_method :from_file_core
+
+      # Shared post-parse steps for every core-path file: remark
+      # attachment, header-remark transfer, and path wiring.
+      def self.finalize_loaded_file(exp_file, source, schema_file,
+                                    include_source: nil)
+        RemarkAttacher.new(source).attach(exp_file) if source && include_source != false
+
+        transfer_header_to_schema(exp_file, source)
+
+        exp_file.path = schema_file
+        exp_file.schemas.each do |schema|
+          schema.file = schema_file
+          schema.file_basename = File.basename(schema_file, ".exp")
+        end
+      end
+      private_class_method :finalize_loaded_file
+
+      # Whether the native batch compiler is usable: the extension is
+      # loaded and exposes BatchStream.
+      def self.batch_available?
+        Core::NATIVE_AVAILABLE &&
+          ::Expressir::Core.const_defined?(:BatchStream, false)
+      end
+      private_class_method :batch_available?
+
+      # Whether the compiled-set artifact APIs are exposed.
+      def self.core_set_available?
+        Core::NATIVE_AVAILABLE && ::Expressir::Core.const_defined?(:Set, false)
+      end
+      private_class_method :core_set_available?
+
+      # Concurrent core-path parse: workers compile in the background
+      # while this thread hydrates, attaches remarks, and reports
+      # progress per file. Results keep the input order; a file that
+      # fails to parse is nil-padded exactly like the other paths.
+      def self.from_files_batch(files, include_source: nil, root_path: nil,
+                                max_processes: nil, compiled_set_out: nil,
+                                &progress)
+        schema_file_for = lambda do |file|
+          root_path ? Pathname.new(file.to_s).relative_path_from(root_path).to_s : file.to_s
+        end
+        wire_paths = files.map { |f| schema_file_for.call(f) }
+        physical = wire_paths.zip(files.map(&:to_s)).to_h
+
+        results = {}
+        jobs = files.map { |f| [f.to_s, schema_file_for.call(f)] }
+        # Outcomes arrive in completion order; files are finalized and
+        # reported in input order (the contract every other path keeps).
+        pending = {}
+        stream = ::Expressir::Core::BatchStream.start(jobs, max_processes.to_i)
+        cursor = 0
+        while (item = stream.next)
+          wire_path, model, error = item
+          if error
+            # Unreadable sources raise like every other path; parse
+            # failures nil-pad and report.
+            raise Errno::ENOENT, error if error.start_with?("read ")
+
+            pending[wire_path] = [nil, error]
+          else
+            pending[wire_path] = [model, nil]
+          end
+          while (entry = pending[wire_paths[cursor]])
+            pending.delete(wire_paths[cursor])
+            ordered_path = wire_paths[cursor]
+            file = physical[ordered_path]
+            loaded, load_error = entry
+            if loaded
+              source = strip_bom(File.read(file))
+              loaded.wire_parents
+              finalize_loaded_file(loaded, source, ordered_path,
+                                   include_source: include_source)
+              results[ordered_path] = loaded
+              yield(file, loaded, nil)
+            else
+              results[ordered_path] = nil
+              yield(file, nil,
+                    Error::SchemaParseFailure.new(ordered_path,
+                                                  RuntimeError.new(load_error)))
+            end
+            cursor += 1
+          end
+        end
+
+        if compiled_set_out && !results.value?(nil)
+          stream.write_set(compiled_set_out, physical,
+                           Expressir::Version::VERSION)
+          RemarkOverlay.write(compiled_set_out, results.values.compact)
+        end
+
+        wire_paths.map { |wire_path| results[wire_path] }
+      end
+      private_class_method :from_files_batch
+
+      # Warm start from a compiled-set artifact. Returns nil (caller
+      # falls back to compiling) when the artifact is unreadable or no
+      # longer matches the sources. Remarks are re-attached from the
+      # source files and references are resolved as usual — everything
+      # not carried by the wire is deterministic and cheap to rebuild.
+      def self.from_compiled_set(path, files, skip_references: nil,
+                                 include_source: nil, root_path: nil, &progress)
+        schema_file_for = lambda do |file|
+          root_path ? Pathname.new(file.to_s).relative_path_from(root_path).to_s : file.to_s
+        end
+        physical = files.to_h { |f| [schema_file_for.call(f), f.to_s] }
+
+        set = begin
+          ::Expressir::Core::Set.open(path)
+        rescue StandardError
+          nil
+        end
+        return nil if set.nil?
+        return nil unless set.matches_sources(physical) == true
+
+        models = []
+        while (pair = set.next)
+          wire_path, model = pair
+          file = physical[wire_path]
+          # The artifact wire is pre-remark; the overlay carries them
+          # (plus header remarks and remark-derived structures), so the
+          # RemarkAttacher never runs on a warm load.
+          model.wire_parents
+          finalize_loaded_file(model, nil, wire_path,
+                               include_source: include_source)
+          models << model
+          progress&.call(file || wire_path, model.schemas, nil)
+        end
+        RemarkOverlay.apply(path, models)
+
+        repository = build_repository(models, skip_references: true)
+        graph_path = "#{path}.graph.json"
+        if File.exist?(graph_path)
+          require "json"
+          repository.item_graph =
+            Model::Indexes::ItemGraph.from_tables(JSON.parse(File.read(graph_path)))
+        end
+        if skip_references || RefsOverlay.apply_to(path, models)
+          # Either explicitly skipping resolution or the compiled-set
+          # refs sidecar already re-bound the references.
+        else
+          Expressir::Benchmark.measure_references do
+            ResolveReferencesModelVisitor.new.visit(repository)
+          end
+        end
+        repository
       end
+      private_class_method :from_compiled_set
 
       def self.parse_files_sequentially(files, skip_references: nil,
 include_source: nil, root_path: nil, use_native: nil, &block)

data/lib/expressir/express/pretty_gate.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Pretty round-trip gate (parity-ee stage 08 / eeng qualify.sh
+    # self-check): parse → format → re-parse and compare a structural
+    # fingerprint of the model. Byte identity is deliberately not
+    # required — remark placement and whitespace drift are tolerated;
+    # declaration inventory and interface shape must match.
+    class PrettyGate
+      Result = Struct.new(:path, :ok, :before, :after, :error, keyword_init: true)
+
+      def self.fingerprint(schema)
+        {
+          id: schema.id&.safe_downcase,
+          interfaces: Array(schema.interfaces).map do |i|
+            {
+              kind: i.kind,
+              schema: (i.schema.is_a?(String) ? i.schema : i.schema&.id)&.safe_downcase,
+              items: Array(i.items).map do |entry|
+                ref = entry.ref.is_a?(String) ? entry.ref : entry.ref&.id
+                [entry.id&.safe_downcase, ref&.safe_downcase]
+              end.sort,
+            }
+          end,
+          constants: ids_of(schema.constants),
+          types: ids_of(schema.types),
+          entities: ids_of(schema.entities),
+          subtype_constraints: ids_of(schema.subtype_constraints),
+          functions: ids_of(schema.functions),
+          procedures: ids_of(schema.procedures),
+          rules: ids_of(schema.rules),
+          entity_attrs: Array(schema.entities).to_h do |e|
+            [e.id.safe_downcase, Array(e.attributes).filter_map { |a| a.id&.safe_downcase }.sort]
+          end,
+        }
+      end
+
+      def self.ids_of(coll)
+        Array(coll).filter_map { |d| d.id&.safe_downcase }.sort
+      end
+
+      def self.check_file(path)
+        source = File.read(path)
+        original = Parser.from_exp(source, skip_references: true)
+        formatted = Formatter.format(original)
+        roundtrip = Parser.from_exp(formatted, skip_references: true)
+
+        before = original.schemas.map { |s| fingerprint(s) }
+        after = roundtrip.schemas.map { |s| fingerprint(s) }
+        Result.new(path: path, ok: before == after, before: before, after: after)
+      rescue StandardError => e
+        Result.new(path: path, ok: false, error: e)
+      end
+
+      def self.check_files(paths)
+        paths.map { |p| check_file(p) }
+      end
+    end
+  end
+end

data/lib/expressir/express/refs_overlay.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Resolved references are deterministic given the sources and the
+    # repository composition, so the batch path persists every
+    # SimpleReference's final base_path as an overlay next to the
+    # compiled-set artifact; warm loads re-apply them instead of
+    # re-running the {ResolveReferencesModelVisitor}.
+    module RefsOverlay
+      module_function
+
+      def write(set_path, models)
+        refs = {}
+        ModelTraversal.each_model(models) do |node, key|
+          next unless node.is_a?(Model::References::SimpleReference)
+          next if node.base_path.nil?
+
+          refs[key] = node.base_path
+        end
+        return if refs.empty?
+
+        require "json"
+        File.write("#{set_path}.refs.json", JSON.generate(refs))
+      end
+
+      # Re-binds resolved references from the compiled-set refs
+      # sidecar. Returns the sidecar path when it was applied (caller
+      # then skips the resolver); nil when absent — caller falls back
+      # to resolving.
+      def apply_to(set_path, models)
+        refs_path = "#{set_path}.refs.json"
+        return nil unless File.exist?(refs_path)
+
+        require "json"
+        refs = JSON.parse(File.read(refs_path))
+        ModelTraversal.each_model(models) do |node, key|
+          next unless node.is_a?(Model::References::SimpleReference)
+
+          base_path = refs[key]
+          node.base_path = base_path unless base_path.nil?
+        end
+        refs_path
+      end
+    end
+  end
+end

data/lib/expressir/express/remark_attacher.rb

@@ -245,21 +245,31 @@ module Expressir
       # shares a line with a node or sits outside any statement-bearing node.
       def find_body_comment_target(remark)
         line = remark.line
-        nodes = @node_index.nodes
         # An own-line comment shares its line with no node. A node STARTING
         # here means the remark is an inline tail (code; -- note). The
         # end-line check is restricted to statements: container end_lines are
         # child-derived approximations that can collide with comment lines.
-        return inline_target(remark, nodes) if inline_remark?(remark)
+        if inline_remark?(remark)
+          target, placement, region = inline_target(remark,
+                                                    @node_index.starting_at(line))
+          return [target, placement, region] if target
+
+          # A remark trailing a mid-construct keyword (`ELSE -- why`) starts
+          # nothing and closes nothing; handled before the legacy fallthrough,
+          # which would hand it to the enclosing construct unplaced — where
+          # nothing renders it.
+          mid = mid_keyword_inline_target(remark)
+          return mid if mid
+        end
 
         # A closing keyword on the next code line is decisive: the comment
         # closes that body. Without this check the comment would instead be
         # read as leading the next statement of an OUTER region, which is
         # where it would wrongly render.
-        closing = closing_region_target(line, nodes)
+        closing = closing_region_target(line)
         return closing if closing.first
 
-        enclosing, region, = statement_region_for(line, nodes)
+        enclosing, region, = statement_region_for(line)
         return [nil, nil, nil] unless region
 
         following = region
@@ -287,21 +297,116 @@ module Expressir
         !content[0...opener].strip.empty?
       end
 
-      # A comment trailing code on its line belongs to the statement that
-      # ends closest before it: `x := 1; -- why`. Only single-line statements
-      # qualify, because appending to a statement spanning several lines
-      # would move the remark down to its closing keyword.
+      # A comment trailing code on its line belongs to the statement it
+      # follows: `x := 1; -- why`, or the opener of a compound one, as in
+      # `IF x THEN -- why`.
+      #
+      # Multi-line statements were once excluded here, because appending a
+      # remark to one would carry it down to its closing keyword. They are
+      # admitted now that the formatter can put an opener remark back on the
+      # first line; the OPENER_REGION on the returned placement is what tells
+      # it to, and without that region the old appending behaviour stands.
       def inline_target(remark, nodes)
-        owner = nodes
+        started_here = nodes.select do |n|
+          n[:node].is_a?(Model::TakesInlineRemark) &&
+            n[:line] == remark.line &&
+            n[:position] && n[:position] < remark.position
+        end
+
+        # Of the two that began here, whichever starts later is the one the
+        # remark follows: `x := 0; IF n > 0 THEN -- why` trails the IF.
+        began = [single_line_owner(started_here, remark.line),
+                 opener_owner(started_here, remark.line)]
+          .compact.max_by { |n| n[:position] }
+
+        owner = began || closing_owner(nodes, remark)
+        return [nil, nil, nil] unless owner
+
+        [owner[:node], Model::RemarkPlacement::INLINE,
+         opener_region(owner, remark.line)]
+      end
+
+      # A node beginning and ending on the remark's line. Ranked by where it
+      # ends, so of several sharing the line the outermost complete one wins:
+      # `CASE n OF 1 : x := 2; END_CASE; -- why` trails the CASE, not its
+      # action.
+      def single_line_owner(candidates, line)
+        candidates
+          .select { |n| n[:end_line] == line }
+          .max_by { |n| n[:position] + n[:node].source.to_s.length }
+      end
+
+      # A node whose opener is on the remark's line but which continues past
+      # it. Ranked by where it STARTS, not where it ends: such a node's source
+      # spans its whole body, so ranking by end would let an enclosing block
+      # outrank the one the remark actually follows.
+      def opener_owner(candidates, line)
+        candidates
+          .select { |n| n[:end_line] && n[:end_line] > line }
+          .max_by { |n| n[:position] }
+      end
+
+      # Nothing began on the remark's line, so it may still be closing one
+      # that began earlier:
+      #
+      #     REFERENCE FROM x
+      #       (a, b); -- why
+      #
+      # Only reached as a fallback. Were it folded into the main lookup, an
+      # enclosing block would become a candidate for every remark inside it,
+      # since a node's end line is derived from its children.
+      def closing_owner(nodes, remark)
+        nodes
           .select do |n|
-            n[:node].is_a?(Model::Statement) &&
-              n[:line] == remark.line && n[:end_line] == remark.line &&
+            n[:node].is_a?(Model::TakesInlineRemark) &&
+              n[:end_line] == remark.line && n[:line] &&
+              n[:line] < remark.line &&
               n[:position] && n[:position] < remark.position
           end
-          .max_by { |n| n[:position] + n[:node].source.to_s.length }
+          .max_by { |n| n[:position] }
+      end
+
+      # A remark trailing a node that closes on its line follows the whole
+      # node, so it is written back the way an ordinary inline remark is. One
+      # that continues past the line trailed the node's opener instead, and
+      # belongs back there rather than after the closing keyword.
+      def opener_region(owner, line)
+        return nil unless owner[:end_line] && owner[:end_line] > line
+
+        Model::RemarkPlacement::OPENER_REGION
+      end
+
+      # Lines beginning with a mid-construct keyword. The keyword closes
+      # nothing and opens nothing, but the remark trailing it belongs to the
+      # construct it branches — written back after the keyword, not after the
+      # construct's END_.
+      MID_KEYWORD_REGIONS = {
+        /\AELSE\b/i => [Model::Statements::If,
+                        Model::RemarkPlacement::ELSE_REGION],
+        /\AOTHERWISE\b/i => [Model::Statements::Case,
+                             Model::RemarkPlacement::OTHERWISE_REGION],
+      }.freeze
+
+      # Attach `ELSE -- why` / `OTHERWISE : -- why` to the innermost
+      # enclosing IF / CASE with INLINE placement and the keyword's region.
+      # Returns [nil, nil, nil] when the line head is no mid-construct
+      # keyword or no construct of the right kind spans the line.
+      def mid_keyword_inline_target(remark)
+        content = line_content_for(remark.line).to_s
+        opener = content.index("--")
+        return [nil, nil, nil] unless opener
+
+        owner = MID_KEYWORD_REGIONS.find { |pattern, _| content[0...opener].strip.match?(pattern) }
         return [nil, nil, nil] unless owner
 
-        [owner[:node], Model::RemarkPlacement::INLINE, nil]
+        klass, region = owner[1]
+        innermost = @node_index.nodes.select do |n|
+          n[:node].is_a?(klass) && n[:line] && n[:end_line] &&
+            n[:line] < remark.line && n[:end_line] > remark.line
+        end.max_by { |n| n[:line] }
+        return [nil, nil, nil] unless innermost
+
+        [innermost[:node], Model::RemarkPlacement::INLINE, region]
       end
 
       # Which closing keyword ends which region of which owner. A comment
@@ -339,7 +444,7 @@ module Expressir
       # every span and never reaches statement_region_for. Resolve it from
       # the keyword that follows: it names both the owner type and the body
       # being closed.
-      def closing_region_target(line, nodes)
+      def closing_region_target(line)
         keyword_owner, region, keyword_line = closing_keyword_after(line)
         return [nil, nil, nil] unless keyword_owner
 
@@ -351,8 +456,8 @@ module Expressir
         opener_line = active_opener_line(keyword_line, keyword_owner)
         return [nil, nil, nil] unless opener_line
 
-        owner = nodes.find do |n|
-          n[:node].is_a?(keyword_owner) && n[:line] == opener_line
+        owner = @node_index.starting_at(opener_line).find do |n|
+          n[:node].is_a?(keyword_owner)
         end
         return [nil, nil, nil] unless owner
 
@@ -458,18 +563,15 @@ module Expressir
         [nil, nil, nil]
       end
 
-      def statement_region_for(line, nodes)
-        candidates = nodes.select do |n|
+      def statement_region_for(line, nodes = nil)
+        candidates = (nodes || @node_index.spanning(line)).select do |n|
           n[:line] && n[:end_line] && n[:line] <= line && n[:end_line] >= line &&
             (n[:node].is_a?(Model::Statement) || function_rule_procedure?(n[:node]))
         end
         enclosing = innermost_candidate(candidates)
         return [nil, nil, nil] unless enclosing
 
-        children = nodes.select do |n|
-          n[:owner].equal?(enclosing[:node]) &&
-            STATEMENT_REGIONS.include?(n[:collection]) && n[:line]
-        end
+        children = @node_index.children_in(enclosing[:node], STATEMENT_REGIONS)
         return [enclosing, nil, nil] if children.empty?
 
         preceding = children.select { |n| n[:line] < line }.max_by { |n| n[:position] }
@@ -870,6 +972,12 @@ module Expressir
                      placement: nil, region: nil, source_offset: nil)
         return unless node
         return unless node.is_a?(Model::ModelElement)
+        # An empty remark body carries no content; storing it produced
+        # remarks == [""] entries (GH-363). Bare `--IPn:` informal
+        # propositions keep their declarations through
+        # create_or_find_informal_proposition, which does not run through
+        # here — only the redundant empty-body storage drops.
+        return if text.nil? || text.strip.empty?
 
         if supports_remarks?(node)
           if node_has_remarks?(node)

data/lib/expressir/express/remark_overlay.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Remarks are deterministic given the sources, so the batch path
+    # persists them as an overlay next to the compiled-set artifact;
+    # warm loads re-apply the overlay instead of re-running the
+    # {RemarkAttacher}.
+    #
+    # Nodes are keyed structurally — attribute path plus array index —
+    # because {Model::ModelElement#path} is empty for id-less nodes
+    # (statements), and the wire is byte-identical between the cold
+    # write and the warm apply, so structural keys match exactly.
+    module RemarkOverlay
+      CAPTURED = %w[remarks remark_items informal_propositions untagged_remarks header].freeze
+
+      class << self
+        def write(set_path, models)
+          overlay = {}
+          ModelTraversal.each_model(models) do |node, key|
+            entry = {}
+            CAPTURED.each do |attr|
+              next unless node.respond_to?(attr)
+
+              value = node.public_send(attr)
+              entry[attr] = value if attr == "header" ? value : value&.any?
+            end
+            overlay[key] = entry if entry.any?
+          end
+          return if overlay.empty?
+
+          require "json"
+          File.write("#{set_path}.remarks.json", JSON.generate(overlay))
+        end
+
+        # Recursively parent restored nodes and invalidate id-memos so
+        # find()/resolve_path_in_scope sees them, exactly as the
+        # RemarkAttacher's own bookkeeping does.
+        def wire_overlay_value(parent, value)
+          case value
+          when Array
+            value.each { |item| wire_overlay_value(parent, item) }
+          when Model::ModelElement
+            parent_value = parent.is_a?(Model::ModelElement) ? parent : nil
+            value.parent = parent_value if value.respond_to?(:parent=)
+            if parent_value.respond_to?(:reset_children_by_id)
+              parent_value.reset_children_by_id
+            end
+            value.class.attributes.each_key do |attr|
+              next if Model::ModelElement::SKIP_ATTRIBUTES.include?(attr) || attr == :parent
+
+              inner = value.public_send(attr)
+              next unless inner.is_a?(Model::ModelElement) || inner.is_a?(Array)
+
+              wire_overlay_value(value, inner)
+            end
+          end
+        end
+
+        def apply(set_path, models)
+          overlay_path = "#{set_path}.remarks.json"
+          return unless File.exist?(overlay_path)
+
+          require "json"
+          overlay = JSON.parse(File.read(overlay_path))
+          ModelTraversal.each_model(models) do |node, key|
+            entry = overlay[key]
+            next unless entry
+
+            CAPTURED.each do |attr|
+              setter = :"#{attr}="
+              next unless entry[attr] && node.respond_to?(setter)
+
+              node.public_send(setter, entry[attr])
+              # The writer casts JSON hashes into model objects; wire
+              # the cast collection (the attacher parents every
+              # created node and resets the child-id memo — reference
+              # resolution relies on both).
+              wire_overlay_value(node, node.public_send(attr))
+            end
+          end
+        end
+      end
+    end
+  end
+end