hecks 3.0.4 → 3.1.0

data/lib/hecks/rust_build/domain_name.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "hecks/vocabulary"
+require "hecks/bluebook/model_check"
+
+module Hecks
+  module RustBuild
+    # Whether a domain's directory name can double as a Rust module identifier and a Cargo
+    # feature name. The reserved-word half is `ModelCheck.rust_reserved_name_findings`, the one
+    # shared check.
+    module DomainName
+      # Every key `rust/Cargo.toml` uses outside `[features]`, plus `default`, which Cargo
+      # reserves for the auto-enabled feature set. Declared once as the `CargoReservedName`
+      # vocabulary.
+      CARGO_RESERVED = Hecks::Vocabulary.fetch("CargoReservedName")
+
+      # @param name [String] the domain's directory name
+      # @return [Boolean] whether it is a plain lowercase identifier and no reserved word
+      def self.valid?(name)
+        text = name.to_s
+        text.match?(/\A[a-z_][a-z0-9_]*\z/) &&
+          Hecks::Bluebook::ModelCheck.rust_reserved_name_findings(domain_name: text).empty?
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/kernel_input.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../rust_build"
+
+module Hecks
+  module RustBuild
+    # The stdin a compiled domain binary reads: the steps to run, plus the declared argument
+    # defaults the host would hand its kernel.
+    #
+    # The kernel has no IR of its own, so a command's declared defaults reach it as a top-level
+    # `"defaults"` table, `{ "Domain::Aggregate.Command" => { "attribute" => value } }`, the same
+    # one the Rust host builds from the domain's IR. A harness that sends only `"steps"` would
+    # leave the kernel refusing an argument Ruby fills, so every conformance caller builds its
+    # input here.
+    module KernelInput
+      module_function
+
+      # @param domain_path [String] the domain's directory; its basename names the generated module
+      # @param steps [Array<Hash>] the steps to run
+      # @return [Hash{String => Object}] the input; `"defaults"` is there only when one is declared
+      def build(domain_path, steps)
+        input = { "steps" => steps }
+        defaults = defaults_for(domain_path)
+        input["defaults"] = defaults unless defaults.empty?
+        input
+      end
+
+      # @param domain_path [String] the domain's directory
+      # @return [String] the input as JSON, ready for the binary's stdin
+      def json(domain_path, steps) = JSON.generate(build(domain_path, steps))
+
+      # Each command's declared defaults, read from the domain's generated IR.
+      #
+      # @param domain_path [String] the domain's directory
+      # @return [Hash{String => Hash{String => Object}}] empty when the IR is absent or has none
+      def defaults_for(domain_path)
+        ir = generated_ir(domain_path) or return {}
+        domain = ir["name"].to_s
+        Array(ir["aggregates"]).each_with_object({}) do |aggregate, table|
+          Array(aggregate["commands"]).each do |command|
+            held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
+                                               .to_h { |attribute| [attribute["name"], attribute["default"]] }
+            table["#{domain}::#{aggregate['name']}.#{command['name']}"] = held unless held.empty?
+          end
+        end
+      end
+
+      # @param domain_path [String] the domain's directory
+      # @return [Hash, nil] the parsed generated IR, or nil when the domain has none
+      def generated_ir(domain_path)
+        feature = File.basename(domain_path.to_s.chomp("/")).downcase
+        path = File.join(RustBuild.rust_dir, "src", "generated", feature, "ir.json")
+        File.file?(path) ? JSON.parse(File.read(path)) : nil
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/project_rust/codegen_run.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tmpdir"
+require_relative "../rust_literal"
+require_relative "../write_if_changed"
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # Generates a domain's Rust by running `hecks-codegen full` on IR the caller built from the
+      # live registry, into a scratch directory, then copies only the files whose bytes changed
+      # into `src/generated/`. An unchanged file keeps its mtime, so Cargo does not rebuild.
+      class CodegenRun
+        META_LABEL = "the self-hosted language (lib/hecks/language/bluebook)"
+
+        # One chapter's IR, generated into its own module.
+        Chapter = Struct.new(:mod_name, :label, :ir)
+
+        # The `hecks-codegen` crate: the workspace's own copy when it carries one (a packaged
+        # workspace does), otherwise the checkout's, so a scratch crate holding only the generated
+        # tree still finds it.
+        #
+        # @param rust_dir [String] the workspace being generated into
+        # @return [String] the crate's directory
+        def self.crate_dir(rust_dir)
+          own = File.join(rust_dir, "codegen")
+          File.directory?(own) ? own : File.join(RustBuild::ROOT, "rust/codegen")
+        end
+
+        # Where Cargo puts the binary: under `CARGO_TARGET_DIR` when a build sets it (a copy of the
+        # packaged workspace does, so nothing is written into the installed gem), else in the crate.
+        #
+        # @param rust_dir [String] the workspace being generated into
+        # @param env [#fetch] the environment Cargo will run with
+        # @return [String] the binary's path
+        def self.binary(rust_dir, env: ENV)
+          target = env.fetch("CARGO_TARGET_DIR") { File.join(crate_dir(rust_dir), "target") }
+          File.join(target, "debug/hecks-codegen")
+        end
+
+        # @param rust_dir [String] the workspace being generated into
+        # @param out_root [String] the crate's `src/generated`
+        # @param target [Chapter] the domain being projected
+        # @param chapters [Array<Chapter>] every other bluebook the target attached
+        # @param meta [Hash] the self-hosted language's IR
+        def initialize(rust_dir:, out_root:, target:, chapters:, meta:)
+          @rust_dir = rust_dir
+          @out_root = out_root
+          @target = target
+          @chapters = chapters
+          @meta = meta
+        end
+
+        # @return [void]
+        # @raise [Failure] when `hecks-codegen` cannot be built or exits non-zero
+        def call
+          build_binary
+          Dir.mktmpdir("hecks-codegen-full") do |tmp|
+            stage = File.join(tmp, "generated")
+            FileUtils.mkdir_p(stage)
+            generate_meta(stage, tmp)
+            generate_target(stage, tmp)
+            sync(stage)
+          end
+        end
+
+        private
+
+        def build_binary
+          dir = self.class.crate_dir(@rust_dir)
+          return if system("cargo", "build", "--quiet", chdir: dir, out: $stdout, err: $stderr)
+
+          raise Failure, "hecks project_rust: cargo build failed in #{dir} — run it there directly to see why"
+        end
+
+        def generate_meta(stage, tmp)
+          ir_path = write_ir(tmp, "meta", @meta)
+          run("full", stage, "meta", META_LABEL, ir_path)
+          write_sidecars(File.join(stage, "meta"), @meta, META_LABEL)
+        end
+
+        def generate_target(stage, tmp)
+          args = [stage, @target.mod_name, @target.label, write_ir(tmp, @target.mod_name, @target.ir)]
+          @chapters.each do |chapter|
+            args.push(chapter.mod_name, chapter.label, write_ir(tmp, chapter.mod_name, chapter.ir))
+          end
+          run("full", *args)
+          [@target, *@chapters].each do |chapter|
+            write_sidecars(File.join(stage, chapter.mod_name), chapter.ir, chapter.label)
+          end
+        end
+
+        def write_ir(tmp, name, tree)
+          path = File.join(tmp, "#{name}_ir.json")
+          File.write(path, JSON.pretty_generate(tree))
+          path
+        end
+
+        # `ir.json` is what `rust/host` reads at runtime, and `metadata.rs` embeds the same text;
+        # the codegen binary writes neither.
+        def write_sidecars(mod_dir, tree, label)
+          text = JSON.pretty_generate(tree)
+          File.write(File.join(mod_dir, "ir.json"), text)
+          File.write(File.join(mod_dir, "metadata.rs"), <<~RUST)
+            // GENERATED by hecks project_rust — #{label}'s own canonical IR,
+            // embedded for runtime self-description. Not read by any dispatch
+            // function in this module — introspection only.
+            pub const IR_JSON: &str = #{RustLiteral.string(text)};
+          RUST
+        end
+
+        def run(*args)
+          return if system(self.class.binary(@rust_dir), *args, out: $stdout, err: $stderr)
+
+          raise Failure, "hecks project_rust: hecks-codegen #{args.first} failed"
+        end
+
+        # Each module directory is tracked, so a file an earlier run wrote and this one did not
+        # (a removed aggregate) is pruned. Pruning waits for the whole copy to succeed: after a
+        # failure, the files not yet reached would look like orphans and be deleted.
+        def sync(stage)
+          Dir.children(stage).sort.each do |name|
+            source = File.join(stage, name)
+            dest = File.join(@out_root, name)
+            WriteIfChanged.push_directory(dest)
+            copy_changed(source, dest)
+            WriteIfChanged.pop_and_prune(dest)
+          end
+        end
+
+        def copy_changed(source, dest)
+          Dir.children(source).sort.each do |file|
+            path = File.join(dest, file)
+            wrote = WriteIfChanged.call(path, File.read(File.join(source, file), encoding: "UTF-8"))
+            puts(wrote ? "wrote #{path}" : "#{path} unchanged")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/project_rust/root_mod.rb

@@ -43,7 +43,7 @@ module Hecks
           @file.puts "// chapter (governance/identity — no merged.rs of its own, so absent"
           @file.puts "// from `domains`) stays unconditional: it has no single feature of its"
           @file.puts "// own to gate behind, and is compiled in by whichever domain(s) attach"
-          @file.puts "// it via `uses_framework`."
+          @file.puts "// it via `attaches`."
         end
 
         def modules

data/lib/hecks/rust_build/project_rust.rb

@@ -5,20 +5,24 @@ require "json"
 require_relative "../../hecks"
 require_relative "../bluebook/meta_validator"
 require_relative "../ports/persistence/plugins/era"
-require_relative "../../../rust/project"
+require_relative "append_optionals"
+require_relative "domain_name"
+require_relative "write_if_changed"
 
 module Hecks
   module RustBuild
     # Generates Rust source for one domain into the workspace's `src/generated/`, and keeps the
-    # workspace's `Cargo.toml` features in step; `rust/project.rb` (`RustProjection`) holds the
-    # architecture of the generator itself.
+    # workspace's `Cargo.toml` features in step.
     #
     #   ProjectRust.call(["path/to/domain"])
     #
+    # `hecks-codegen` is the generator (ADR 0086): this class builds the IR from the live registry
+    # and `CodegenRun` runs the binary on it. `HECKS_CODEGEN=ruby` selects the Ruby generator in
+    # `rust/project` until that is deleted; `HECKS_PARSER=rust` with `HECKS_CODEGEN=rust` runs
+    # `rust/project_rust_pipeline.rb` instead, with no Ruby load of the domain.
+    #
     # The era plugin is required unconditionally so the generator works for any domain, lineage
     # capable or not; `pg` stays lazy inside it, so nothing here opens a database connection.
-    # With `HECKS_PARSER=rust` and `HECKS_CODEGEN=rust` together, the whole pipeline runs through
-    # `rust/project_rust_pipeline.rb` instead, with no Ruby load of the domain.
     class ProjectRust
       # The optional attachments `rust/host` reads from `ir.json`, each omitted when nothing
       # attached provides it: exporter method, then the key it is written under.
@@ -43,6 +47,7 @@ module Hecks
       def call
         validate_name!
         if ENV["HECKS_PARSER"] == "rust" && ENV["HECKS_CODEGEN"] == "rust"
+          require_relative "../../../rust/project"
           require_relative "../../../rust/project_rust_pipeline"
           RustProjectPipeline.call(@domain)
         else
@@ -56,13 +61,13 @@ module Hecks
       # The name becomes a directory, a `pub mod` identifier and a Cargo feature, so it is checked
       # before any side effect (the `meta/` directory is rewritten below).
       def validate_name!
-        return if RustProjection::Projector.valid_domain_mod_name?(@mod_name)
+        return if DomainName.valid?(@mod_name)
 
         raise Failure, "hecks project_rust: domain name #{@mod_name.inspect} (from #{@domain.inspect}) can't " \
                        "be used as-is — it has to double as a Rust module identifier and a Cargo feature " \
                        "name, and this one is either not a plain lowercase identifier, is a Rust keyword, " \
                        "or collides with a reserved Cargo.toml key " \
-                       "(#{RustProjection::Projector::CARGO_RESERVED_DOMAIN_NAMES.join(', ')}). " \
+                       "(#{DomainName::CARGO_RESERVED.join(', ')}). " \
                        "Rename the domain directory."
       end
 
@@ -72,17 +77,45 @@ module Hecks
         @out_root = File.join(@rust_dir, "src/generated")
         FileUtils.mkdir_p(@out_root)
         build_target_ir
-        write_meta
-        write_target
+        FileUtils.rm_rf(File.join(@out_root, "active"))
+        ENV["HECKS_CODEGEN"] == "ruby" ? generate_with_ruby : generate_with_codegen
         write_root_mod
         sync_cargo_features
       end
 
+      # The rollback path (ADR 0086): the Ruby generator in `rust/project`, until it is deleted.
+      def generate_with_ruby
+        require_relative "../../../rust/project"
+        write_meta
+        write_target
+      end
+
+      # `hecks-codegen` is the generator; this process only builds the IR it reads from the live
+      # registry, so a domain's persistence, seams, translations and source text reach `ir.json`.
+      def generate_with_codegen
+        meta = Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
+        vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
+        chapters = (@registry.bluebooks.keys - [@domain_name]).map do |name|
+          ir = Hecks::Projector::Exporter.call(@registry).fetch(name)
+          CodegenRun::Chapter.new(name.downcase, "#{@domain} (#{attachment(name, vendored)})", prepared_ir(ir))
+        end
+        CodegenRun.new(
+          rust_dir: @rust_dir, out_root: @out_root, meta: prepared_ir(meta), chapters: chapters,
+          target: CodegenRun::Chapter.new(@mod_name, @domain, prepared_ir(@ir, shaped: false))
+        ).call
+      end
+
+      # The IR as `rust/project` hands it to its generators: string-keyed through JSON, with the
+      # append-optional fields marked, since `ir.json` records them.
+      def prepared_ir(tree, shaped: true)
+        AppendOptionals.mark(shaped ? json_shaped(tree) : tree)
+      end
+
       # Round-trips a value through JSON so generators see the string-keyed shape a real `ir.json`
       # carries, never live Ruby symbols.
       def json_shaped(payload) = JSON.parse(JSON.generate(payload), symbolize_names: true)
 
-      # `root:` is the domain's own directory: a domain that declares `uses_embryonaut_bluebook`
+      # `root:` is the domain's own directory: a domain that declares `attaches ... from: :vendor`
       # resolves its vendored chapters beneath it.
       def load_registry
         @registry = Hecks::Runtime::Registry.new(root: File.expand_path(@domain))
@@ -100,7 +133,7 @@ module Hecks
         @domain_name = @registry.bluebooks.keys.first
       end
 
-      # Translation edges, hecksagons (whose `uses_framework` loads a framework chapter into the
+      # Translation edges, hecksagons (whose `attaches` loads a framework chapter into the
       # same registry) and worlds (whose `default_adapter` binds what a hecksagon leaves out), in
       # the order the language loads them.
       def load_siblings
@@ -134,7 +167,7 @@ module Hecks
         if !seams[:membership].empty? && seams[:identity].empty?
           raise Failure, "#{@domain_name} provides membership but not identity — rust/host Google sign-in " \
                          "cannot register or link an identity from ir.json. Attach Identity " \
-                         "(`uses_framework \"Identity\"` plus a sibling Hecks.hecksagon \"Identity\") so the " \
+                         "(`attaches \"Identity\"` plus a sibling Hecks.hecksagon \"Identity\") so the " \
                          "hecksagon, not a deploy-time guess, names the identity verbs."
         end
         add_edges_and_source
@@ -163,8 +196,7 @@ module Hecks
         # Tracked per directory: several domains coexist on disk, and `pop_and_prune` deletes only
         # the files this run never touched. `active` is a set of feature re-exports in the root
         # `mod.rs`, never a directory.
-        RustProjection::WriteIfChanged.push_directory(dir)
-        FileUtils.rm_rf(File.join(@out_root, "active"))
+        WriteIfChanged.push_directory(dir)
         result = RustProjection::DomainGenerator.call(
           meta_ir, "the self-hosted language (lib/hecks/language/bluebook)", dir, "meta"
         )
@@ -176,12 +208,12 @@ module Hecks
                      managers: meta_ir[:process_managers],
                      keys:     [[meta_ir[:name], result[:aggregates].map { |a| a[:name] }]])
         append_merged_mod(File.join(dir, "mod.rs"))
-        RustProjection::WriteIfChanged.pop_and_prune(dir)
+        WriteIfChanged.pop_and_prune(dir)
       end
 
       def write_target
         dir = File.join(@out_root, @mod_name)
-        RustProjection::WriteIfChanged.push_directory(dir)
+        WriteIfChanged.push_directory(dir)
         result = RustProjection::DomainGenerator.call(@ir, @domain, dir, @mod_name)
         chapters = write_chapters
         aggregates = result[:aggregates] + chapters[:aggregates]
@@ -192,10 +224,10 @@ module Hecks
                      managers: @ir[:process_managers] + chapters[:process_managers],
                      keys:     reference_keys(result[:aggregates], chapters))
         append_merged_mod(File.join(dir, "mod.rs"))
-        RustProjection::WriteIfChanged.pop_and_prune(dir)
+        WriteIfChanged.pop_and_prune(dir)
       end
 
-      # Every other bluebook the target's `uses_framework` calls pulled into the registry, each
+      # Every other bluebook the target's `attaches` calls pulled into the registry, each
       # generated into its own module. A framework chapter is a function of its bluebook alone, so
       # regenerating one is safe whichever domain last touched it.
       def write_chapters
@@ -203,7 +235,7 @@ module Hecks
                    policy_sources: [{ domain_name: @domain_name, policies: @ir[:policies],
                                       aggregates: @ir[:aggregates] }],
                    mod_names: { @mod_name => @domain_name } }
-        vendored = @registry.hecksagons.values.flat_map(&:vendored_bluebooks)
+        vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
         (@registry.bluebooks.keys - [@domain_name]).each { |chapter| write_chapter(chapter, vendored, totals) }
         totals
       end
@@ -213,7 +245,7 @@ module Hecks
         totals[:mod_names][mod_name] = chapter_name
         chapter_ir = json_shaped(Hecks::Projector::Exporter.call(@registry).fetch(chapter_name))
         result = nil
-        RustProjection::WriteIfChanged.track_directory(File.join(@out_root, mod_name)) do
+        WriteIfChanged.track_directory(File.join(@out_root, mod_name)) do
           result = RustProjection::DomainGenerator.call(chapter_ir, "#{@domain} (#{attachment(chapter_name, vendored)})",
                                                         File.join(@out_root, mod_name), mod_name,
                                                         merged_module: false)
@@ -230,7 +262,7 @@ module Hecks
       # sibling hecksagon vendors in is labelled as vendored.
       def attachment(chapter_name, vendored)
         name = vendored.find { |candidate| Hecks::Naming.pascal(candidate.to_s) == chapter_name }
-        name ? "uses_embryonaut_bluebook #{name.inspect}" : "uses_framework #{chapter_name.inspect}"
+        name ? "attaches #{name.inspect}, from: :vendor" : "attaches #{chapter_name.inspect}"
       end
 
       def reference_keys(target_aggregates, chapters)
@@ -243,7 +275,7 @@ module Hecks
       # Writes a module's `merged.rs`: the registry and every dispatch table over its aggregates.
       def write_merged(path, aggregates, queries, read_models, policies:, cross:, managers:, keys:)
         projector = RustProjection::Projector
-        wrote = RustProjection::WriteIfChanged.block(path) do |file|
+        wrote = WriteIfChanged.block(path) do |file|
           [projector.emit_registry(aggregates), projector.emit_reference_lookup(aggregates), policies, cross,
            projector.emit_process_manager_table(managers), projector.emit_reference_key_table(keys),
            projector.emit_creates_table(aggregates), projector.emit_identity_head_table(aggregates),
@@ -280,7 +312,7 @@ module Hecks
         all_dirs = Dir.children(@out_root).select { |name| File.directory?(File.join(@out_root, name)) }.sort
         @domains = all_dirs.select { |name| File.exist?(File.join(@out_root, name, "merged.rs")) }
         path = File.join(@out_root, "mod.rs")
-        wrote = RustProjection::WriteIfChanged.block(path) do |file|
+        wrote = WriteIfChanged.block(path) do |file|
           RootMod.new(file, all_dirs, @domains, @mod_name).write
         end
         puts(wrote ? "wrote #{path}" : "#{path} unchanged")
@@ -296,7 +328,7 @@ module Hecks
         @domains.each { |name| manifest = add_feature(manifest, name) }
         manifest = manifest.sub(/^default\s*=.*$/, "default = [#{@mod_name.inspect}]")
         # An unchanged manifest is not rewritten: a new mtime makes Cargo rebuild the whole crate.
-        if RustProjection::WriteIfChanged.call(path, manifest)
+        if WriteIfChanged.call(path, manifest)
           puts "wrote #{path} (default feature: #{@mod_name})"
         else
           puts "#{path} unchanged (default feature already #{@mod_name})"
@@ -330,3 +362,4 @@ module Hecks
 end
 
 require_relative "project_rust/root_mod"
+require_relative "project_rust/codegen_run"

data/lib/hecks/rust_build/rust_literal.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    # Rust string literals. Ruby's `String#inspect` escapes for Ruby's own read-back (a
+    # brace-less `\uXXXX`, for one), which is not valid Rust syntax.
+    module RustLiteral
+      # Escapes only what Rust's string-literal grammar needs: backslash, double quote and
+      # control characters.
+      #
+      # @param text [#to_s] the text to embed
+      # @return [String] the quoted literal
+      def self.string(text)
+        escaped = text.to_s.each_char.map { |char| escape(char) }.join
+        "\"#{escaped}\""
+      end
+
+      def self.escape(char)
+        case char
+        when "\\" then "\\\\"
+        when "\"" then "\\\""
+        when "\n" then "\\n"
+        when "\r" then "\\r"
+        when "\t" then "\\t"
+        else
+          code = char.ord
+          code < 0x20 || code == 0x7F ? format("\\u{%x}", code) : char
+        end
+      end
+      private_class_method :escape
+    end
+  end
+end

data/lib/hecks/rust_build/write_if_changed.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Hecks
+  module RustBuild
+    # Skips writes whose content is unchanged so file mtimes stay stable.
+    # A rewrite alone forces Cargo to rebuild downstream crates.
+    module WriteIfChanged
+      module_function
+
+      # Records every path written or confirmed unchanged inside the block, then deletes
+      # files left in `dir` that were never touched (orphans of removed aggregates).
+      # Every write is recorded against every open ancestor directory.
+      # `push_directory`/`pop_and_prune` are the same operation split for non-adjacent writes.
+      def track_directory(dir)
+        push_directory(dir)
+        yield
+      ensure
+        pop_and_prune(dir)
+      end
+
+      def push_directory(dir)
+        FileUtils.mkdir_p(dir)
+        stack.push([File.expand_path(dir), Set.new])
+      end
+
+      # Matches by directory, not LIFO: nested directories can close out of order.
+      def pop_and_prune(dir)
+        abs_dir = File.expand_path(dir)
+        idx = stack.rindex { |tracked_dir, _| tracked_dir == abs_dir }
+        return unless idx
+
+        _dir, touched = stack.delete_at(idx)
+        existing = Dir.glob(File.join(abs_dir, "*"))
+        (existing - touched.to_a).each do |orphan|
+          FileUtils.rm_rf(orphan)
+          puts "pruned #{orphan} (no longer generated)"
+        end
+      end
+
+      def stack
+        Thread.current[:hecks_write_if_changed_stack] ||= []
+      end
+      private_class_method :stack
+
+      def record_touch(path)
+        abs = File.expand_path(path)
+        stack.each do |dir, touched|
+          touched << abs if abs.start_with?("#{dir}/")
+        end
+      end
+      private_class_method :record_touch
+
+      # Writes `content` to `path` unless it already holds identical bytes.
+      # Returns whether it wrote.
+      def call(path, content)
+        record_touch(path)
+        # `.b` on both sides: String#== is encoding-aware, so UTF-8 vs ASCII-8BIT
+        # content can compare unequal even when the bytes are identical.
+        return false if File.exist?(path) && File.binread(path) == content.b
+
+        File.write(path, content)
+        true
+      end
+
+      # Like `call`, for callers that build content by writing to an IO. Yields a sibling
+      # temp file, then renames it into place only if the bytes differ. Returns whether it wrote.
+      def block(path, &)
+        record_touch(path)
+        tmp = "#{path}.tmp-#{Process.pid}-#{rand(1_000_000)}"
+        begin
+          File.open(tmp, "w", &)
+          if File.exist?(path) && FileUtils.compare_file(tmp, path)
+            false
+          else
+            FileUtils.mv(tmp, path)
+            true
+          end
+        ensure
+          FileUtils.rm_f(tmp)
+        end
+      end
+    end
+  end
+end