hecks 2.8.0 → 3.0.0

data/lib/hecks/rust_build/native_build.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "open3"
+
+module Hecks
+  module RustBuild
+    # Builds the native binary for one generated domain's Cargo feature, once per workspace.
+    #
+    # Examples interleave, and alternating `--features` builds forces a full recompile each time,
+    # so a built binary is cached per `[rust_dir, feature, sources]`, where `sources` is a digest of
+    # the workspace's Rust sources and manifests. Regenerating the domain changes the digest, so the
+    # next call rebuilds instead of answering with a stale binary or a stale failure.
+    module NativeBuild
+      # Raised when a declared feature fails to build; nil is reserved for "feature not declared".
+      class BuildFailed < StandardError; end
+
+      @cache = {}
+
+      class << self
+        # @return [Hash{Array => String, BuildFailed, nil}] each build's answer, keyed by
+        #   `[rust_dir, feature, sources_digest]`
+        attr_reader :cache
+      end
+
+      module_function
+
+      # Builds the binary for `domain_feature` once per (rust_dir, feature, sources) and
+      # memoizes the result.
+      #
+      # @param domain_feature [String] the Cargo feature, a domain's directory basename
+      # @param rust_dir [String] the workspace to build in
+      # @return [String, nil] the pinned binary, or nil when Cargo.toml declares no such feature
+      # @raise [BuildFailed] when the build fails (memoized too)
+      def build_rust_for(domain_feature, rust_dir)
+        cache = NativeBuild.cache
+        key = [rust_dir, domain_feature, sources_digest(rust_dir)]
+        if cache.key?(key)
+          raise cache[key] if cache[key].is_a?(BuildFailed)
+
+          return cache[key]
+        end
+
+        manifest = File.read(File.join(rust_dir, "Cargo.toml"))
+        return cache[key] = nil unless manifest =~ /^#{Regexp.escape(domain_feature)}\s*=\s*\[\]/
+
+        begin
+          cache[key] = build_and_pin(domain_feature, rust_dir)
+        rescue BuildFailed => e
+          cache[key] = e
+          raise
+        end
+      end
+
+      # Fingerprints what a build reads: every `.rs`, `.toml` and `Cargo.lock` file under the
+      # workspace outside `target/`, by path, size and modification time.
+      #
+      # @param rust_dir [String] the workspace
+      # @return [String] a hex digest that changes when any of those files does
+      def sources_digest(rust_dir)
+        digest = Digest::SHA256.new
+        Dir.glob(File.join(rust_dir, "**", "*.{rs,toml}"), File::FNM_DOTMATCH).sort.each do |path|
+          digest_file(digest, path, rust_dir)
+        end
+        lock = File.join(rust_dir, "Cargo.lock")
+        digest_file(digest, lock, rust_dir) if File.file?(lock)
+        digest.hexdigest
+      end
+
+      def digest_file(digest, path, rust_dir)
+        relative = path.delete_prefix("#{rust_dir}/")
+        return if relative.start_with?("target/") || !File.file?(path)
+
+        stat = File.stat(path)
+        digest << "#{relative}\0#{stat.size}\0#{stat.mtime.to_i}.#{stat.mtime.nsec}\n"
+      end
+
+      # Holds an exclusive flock from `cargo build` through the copy-out: parallel sweeps share
+      # `target/debug/rust`, and another build could overwrite it before it is pinned. The lock
+      # file is left on disk.
+      #
+      # @param domain_feature [String] the Cargo feature
+      # @param rust_dir [String] the workspace to build in
+      # @return [String] the binary, pinned to `target/debug/rust-<feature>`
+      # @raise [BuildFailed] when the build fails or leaves no binary
+      def build_and_pin(domain_feature, rust_dir)
+        lock_path = File.join(rust_dir, "target", ".build_rust_for.lock")
+        FileUtils.mkdir_p(File.dirname(lock_path))
+
+        File.open(lock_path, File::CREAT | File::RDWR) do |lock|
+          lock.flock(File::LOCK_EX)
+          command = ["cargo", "build", "--no-default-features", "--features", domain_feature]
+          cargo(command, rust_dir, domain_feature)
+          pin(rust_dir, domain_feature, command)
+        end
+      end
+
+      def cargo(command, rust_dir, domain_feature)
+        _stdout, stderr, status = Open3.capture3(*command, chdir: rust_dir)
+        return if status.success?
+
+        raise BuildFailed, "`#{command.join(' ')}` failed in #{rust_dir} (exit #{status.exitstatus}) — " \
+                           "#{domain_feature} is declared in Cargo.toml, so this is a build failure, " \
+                           "not a missing feature:\n#{stderr}"
+      rescue SystemCallError => e
+        raise BuildFailed, "`#{command.join(' ')}` could not run in #{rust_dir}: #{e.message}"
+      end
+
+      # `cargo build` always writes the same path; it is pinned per feature while the lock is held.
+      def pin(rust_dir, domain_feature, command)
+        binary = File.join(rust_dir, "target", "debug", "rust")
+        unless File.executable?(binary)
+          raise BuildFailed, "`#{command.join(' ')}` succeeded in #{rust_dir} but left no executable at #{binary}"
+        end
+
+        pinned = File.join(rust_dir, "target", "debug", "rust-#{domain_feature}")
+        FileUtils.cp(binary, pinned)
+        File.chmod(0o755, pinned)
+        pinned
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # Writes `src/generated/mod.rs`: a `pub mod` per generated directory, the feature-gated
+      # `active` re-export of the selected domain, and a `compile_error!` for each pair of
+      # non-default domain features enabled together.
+      class RootMod
+        # @param file [IO] where the module is written
+        # @param directories [Array<String>] every directory under `src/generated`
+        # @param domains [Array<String>] the directories that carry their own `merged.rs`
+        # @param default [String] the domain this run generated, whose feature is the default
+        def initialize(file, directories, domains, default)
+          @file = file
+          @directories = directories
+          @domains = domains
+          @default = default
+        end
+
+        # @return [void]
+        def write
+          banner
+          modules
+          active_notes
+          reexports
+          conflict_guards
+        end
+
+        private
+
+        def banner
+          @file.puts "// GENERATED by hecks project_rust — re-run it to refresh this list."
+          @file.puts "//"
+          @file.puts "// BUG#25 — every DOMAIN (an entry in `domains`, below: a directory"
+          @file.puts "// carrying its own merged.rs and therefore its own Cargo feature) is"
+          @file.puts "// declared behind that SAME feature, so a broken or absent domain's"
+          @file.puts "// generated code is never even compiled into a build that selects a"
+          @file.puts "// DIFFERENT domain — `cargo build --features waybill` used to pull in"
+          @file.puts "// every OTHER domain's `pub mod` unconditionally, so one domain's own"
+          @file.puts "// non-compiling generated code (a `has_many` field, before this fix)"
+          @file.puts "// broke every feature's build, not just its own. A shared FRAMEWORK"
+          @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`."
+        end
+
+        def modules
+          @directories.each do |name|
+            @file.puts "#[cfg(feature = #{name.inspect})]" if @domains.include?(name)
+            @file.puts "pub mod #{name};"
+          end
+        end
+
+        def active_notes
+          @file.puts
+          @file.puts "// `active` is whichever ONE domain's own merged Store/dispatch table"
+          @file.puts "// is selected by Cargo feature (rust/Cargo.toml, kept in sync with this"
+          @file.puts "// list by hecks project_rust) — kernel/cli.rs imports"
+          @file.puts "// `crate::generated::active::{dispatch_by_name, Store, ...}` unchanged"
+          @file.puts "// no matter which domain that resolves to."
+          @file.puts "//"
+          @file.puts "// DOMAIN FEATURES ARE MUTUALLY EXCLUSIVE (R5) — Cargo has no native"
+          @file.puts "// concept of that, and `default = [#{@default.inspect}]` in"
+          @file.puts "// Cargo.toml stays enabled unless a build passes"
+          @file.puts "// `--no-default-features`, so a plain `cargo build --features banking`"
+          @file.puts "// used to enable BOTH the default domain's feature and banking's,"
+          @file.puts "// producing two `pub use ... as active;` imports and a hard E0252."
+          @file.puts "// Fixed two ways below, entirely mechanically from `domains`/"
+          @file.puts "// `target_mod_name` (this run's new default) — never hand-maintained:"
+          @file.puts "//"
+          @file.puts "//   1. THE DEFAULT DOMAIN'S OWN re-export backs off whenever any OTHER"
+          @file.puts "//      domain feature is also enabled, so it never contends for `active`"
+          @file.puts "//      by accident — `cargo build --features banking` (still implicitly"
+          @file.puts "//      carrying the default feature) now resolves to banking alone,"
+          @file.puts "//      same as if `--no-default-features` had been passed explicitly."
+          @file.puts "//   2. Two NON-default domain features enabled TOGETHER (a genuine,"
+          @file.puts "//      not-accidental conflict — nothing makes that combination"
+          @file.puts "//      meaningful) still fail the build, but with an explicit"
+          @file.puts "//      `compile_error!` naming both features instead of a cryptic"
+          @file.puts "//      \"defined multiple times\"."
+        end
+
+        def reexports
+          @domains.each do |name|
+            other_domains = @domains - [name]
+            if name == @default && !other_domains.empty?
+              guard = other_domains.map { |o| "feature = #{o.inspect}" }.join(", ")
+              @file.puts "#[cfg(all(feature = #{name.inspect}, not(any(#{guard}))))]"
+            else
+              @file.puts "#[cfg(feature = #{name.inspect})]"
+            end
+            @file.puts "pub use #{name}::merged as active;"
+          end
+        end
+
+        def conflict_guards
+          non_default_domains = @domains - [@default]
+          if non_default_domains.size > 1
+            @file.puts
+            @file.puts "// Explicit conflict guard — see point 2 above. Only fires when TWO"
+            @file.puts "// non-default domain features are both turned on; the default"
+            @file.puts "// domain's own feature never reaches here (point 1 already excludes"
+            @file.puts "// it whenever any other domain feature is present)."
+            non_default_domains.combination(2).each do |a, b|
+              @file.puts "#[cfg(all(feature = #{a.inspect}, feature = #{b.inspect}))]"
+              # Plain `a`/`b`/`domains.join` here, never `.inspect` — this whole
+              # line already sits inside one Rust string literal
+              # (`compile_error!("...")`), and `.inspect`'s own quoted form
+              # would nest unescaped double quotes and produce invalid Rust.
+              @file.puts "compile_error!(\"domain features are mutually exclusive — enable only one of: #{@domains.join(', ')} " \
+                         "(both #{a} and #{b} are enabled)\");"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/project_rust.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require_relative "../../hecks"
+require_relative "../bluebook/meta_validator"
+require_relative "../ports/persistence/plugins/era"
+require_relative "../../../rust/project"
+
+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.
+    #
+    #   ProjectRust.call(["path/to/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.
+      SEAMS = %i[authorization membership identity newsletter newsletter_issues payments
+                 registrations payment_connection].freeze
+
+      # @param argv [Array<String>] the domain's directory
+      # @return [Integer] the exit status
+      # @raise [Failure] when the domain's name cannot be a Rust module and Cargo feature name
+      def self.call(argv)
+        domain = argv.first or raise Failure, "usage: hecks project_rust <domain>"
+        new(domain).call
+      end
+
+      # @param domain [String] the domain's directory
+      def initialize(domain)
+        @domain = domain
+        @mod_name = File.basename(domain)
+      end
+
+      # @return [Integer] the exit status
+      def call
+        validate_name!
+        if ENV["HECKS_PARSER"] == "rust" && ENV["HECKS_CODEGEN"] == "rust"
+          require_relative "../../../rust/project_rust_pipeline"
+          RustProjectPipeline.call(@domain)
+        else
+          generate
+        end
+        0
+      end
+
+      private
+
+      # 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)
+
+        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(', ')}). " \
+                       "Rename the domain directory."
+      end
+
+      def generate
+        load_registry
+        @rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(RustBuild::ROOT, "rust"))
+        @out_root = File.join(@rust_dir, "src/generated")
+        FileUtils.mkdir_p(@out_root)
+        build_target_ir
+        write_meta
+        write_target
+        write_root_mod
+        sync_cargo_features
+      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`
+      # resolves its vendored chapters beneath it.
+      def load_registry
+        @registry = Hecks::Runtime::Registry.new(root: File.expand_path(@domain))
+        Hecks.with_registry(@registry) do
+          lib = File.expand_path("..", __dir__)
+          %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
+             adapters/driven/prism.adapter adapters/driven/postgres_era.adapter].each do |file|
+            Kernel.load(File.join(lib, file))
+          end
+          @bluebook_dir = File.join(@domain, "bluebook")
+          Hecks::Adapters::Folder.new.load_bluebooks(@bluebook_dir)
+          load_siblings
+          load_environment
+        end
+        @domain_name = @registry.bluebooks.keys.first
+      end
+
+      # Translation edges, hecksagons (whose `uses_framework` 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
+        Dir[File.join(@bluebook_dir, "translations", "*.bluebook")].each { |file| Kernel.load(file) }
+        Dir.glob(File.join(@bluebook_dir, "*.hecksagon")).each { |file| Kernel.load(file) }
+        Dir.glob(File.join(@bluebook_dir, "*.world")).each { |file| Kernel.load(file) }
+      end
+
+      # Production is the default environment when `environments/production.hecksagon` exists
+      # (`rust/host` is the production runtime); `HECKS_PROJECT_ENVIRONMENT` overrides it.
+      def load_environment
+        environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT") do
+          File.exist?(File.join(@bluebook_dir, "environments", "production.hecksagon")) ? "production" : nil
+        end
+        return if environment.nil? || environment.empty?
+
+        folder = Hecks::Adapters::Folder.new
+        folder.load_each(@bluebook_dir, [File.join("environments", "#{environment}.hecksagon")])
+        folder.load_each(@bluebook_dir, [File.join("environments", "#{environment}.world")])
+      end
+
+      # The target's IR, with the binding facts that ride beside it (they are not shape facts, so
+      # `bluebook.to_h` never mentions them).
+      def build_target_ir
+        exporter = Hecks::Projector::Exporter
+        @ir = json_shaped(exporter.call(@registry).fetch(@domain_name))
+        @ir[:lineage] = json_shaped(exporter.lineage(@registry, @domain_name))
+        @ir[:persistence] = json_shaped(exporter.persistence(@registry, @domain_name))
+        seams = SEAMS.to_h { |seam| [seam, exporter.public_send(seam, @registry, @domain_name)] }
+        seams.each { |seam, value| @ir[seam] = json_shaped(value) unless value.empty? }
+        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 " \
+                         "hecksagon, not a deploy-time guess, names the identity verbs."
+        end
+        add_edges_and_source
+      end
+
+      # Edges carry their own precompiled SQL, so a boot-time mint only executes it. Committed
+      # approvals sit beside the edges. The source text is verbatim: the era's integrity digest is
+      # the SHA256 of it, not of anything re-derived from the parsed IR.
+      def add_edges_and_source
+        edges = Hecks::Projector::Exporter.translations(@registry).select { |edge| edge[:domain] == @domain_name }
+        @ir[:translations] = json_shaped(edges)
+        approvals = Hecks::Translation::ApprovalFile.read_all(@bluebook_dir)
+        @ir[:approvals] = json_shaped(approvals) unless approvals.empty?
+        @ir[:source_text] = Hecks::Runtime::EraCheck.source_text_for(
+          @registry.bluebooks.fetch(@domain_name), @bluebook_dir, registry: @registry
+        )
+      end
+
+      # The self-hosted language goes through the same codegen as the target, read from the
+      # grammar registry `MetaValidator` boots with.
+      def write_meta
+        meta_ir = json_shaped(
+          Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
+        )
+        dir = File.join(@out_root, "meta")
+        # 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"))
+        result = RustProjection::DomainGenerator.call(
+          meta_ir, "the self-hosted language (lib/hecks/language/bluebook)", dir, "meta"
+        )
+        write_merged(File.join(dir, "merged.rs"), result[:aggregates], result[:queries], result[:read_models],
+                     policies: RustProjection::Projector.emit_policy_table(meta_ir[:name], meta_ir[:policies],
+                                                                           meta_ir[:aggregates]),
+                     cross:    RustProjection::Projector.emit_cross_domain_policy_table(meta_ir[:name],
+                                                                                        meta_ir[:policies]),
+                     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)
+      end
+
+      def write_target
+        dir = File.join(@out_root, @mod_name)
+        RustProjection::WriteIfChanged.push_directory(dir)
+        result = RustProjection::DomainGenerator.call(@ir, @domain, dir, @mod_name)
+        chapters = write_chapters
+        aggregates = result[:aggregates] + chapters[:aggregates]
+        write_merged(File.join(dir, "merged.rs"), aggregates, result[:queries] + chapters[:queries],
+                     result[:read_models] + chapters[:read_models],
+                     policies: RustProjection::Projector.emit_merged_policy_table(chapters[:policy_sources]),
+                     cross:    RustProjection::Projector.emit_merged_cross_domain_policy_table(chapters[:policy_sources]),
+                     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)
+      end
+
+      # Every other bluebook the target's `uses_framework` 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
+        totals = { aggregates: [], queries: [], read_models: [], process_managers: [],
+                   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)
+        (@registry.bluebooks.keys - [@domain_name]).each { |chapter| write_chapter(chapter, vendored, totals) }
+        totals
+      end
+
+      def write_chapter(chapter_name, vendored, totals)
+        mod_name = chapter_name.downcase
+        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
+          result = RustProjection::DomainGenerator.call(chapter_ir, "#{@domain} (#{attachment(chapter_name, vendored)})",
+                                                        File.join(@out_root, mod_name), mod_name,
+                                                        merged_module: false)
+        end
+        totals[:aggregates].concat(result[:aggregates])
+        totals[:queries].concat(result[:queries])
+        totals[:read_models].concat(result[:read_models])
+        totals[:process_managers].concat(chapter_ir[:process_managers])
+        totals[:policy_sources] << { domain_name: chapter_name, policies: chapter_ir[:policies],
+                                     aggregates: chapter_ir[:aggregates] }
+      end
+
+      # How the target attached a chapter, across every hecksagon the registry loaded: a chapter a
+      # 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}"
+      end
+
+      def reference_keys(target_aggregates, chapters)
+        chapters[:mod_names].map do |mod_name, chapter_name|
+          own = mod_name == @mod_name ? target_aggregates : chapters[:aggregates].select { |a| a[:chapter_mod] == mod_name }
+          [chapter_name, own.map { |a| a[:name] }]
+        end
+      end
+
+      # 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|
+          [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),
+           projector.emit_entity_identity_head_table(aggregates),
+           projector.emit_command_attributes_table(aggregates), projector.emit_query_table(queries),
+           projector.emit_query_arg_check_table(queries)].each do |table|
+            file.puts table
+            file.puts
+          end
+          # A read model's `group_by` function is written before the table names it.
+          read_models.each do |model|
+            next unless model[:group_by_fn_body]
+
+            file.puts model[:group_by_fn_body]
+            file.puts
+          end
+          file.puts projector.emit_read_model_table(read_models)
+        end
+        puts(wrote ? "wrote #{path}" : "#{path} unchanged")
+      end
+
+      # Appends the `pub mod merged;` line once; appending it again would grow the file and bump
+      # its mtime on every run.
+      def append_merged_mod(path)
+        return if File.exist?(path) && File.read(path).include?("pub mod merged;")
+
+        File.open(path, "a") { |file| file.puts "pub mod merged;" }
+      end
+
+      # `src/generated/mod.rs`: every domain ever generated, scanned off disk. A directory is a
+      # selectable domain exactly when it carries its own `merged.rs`; a framework chapter has
+      # none and is always compiled in.
+      def write_root_mod
+        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|
+          RootMod.new(file, all_dirs, @domains, @mod_name).write
+        end
+        puts(wrote ? "wrote #{path}" : "#{path} unchanged")
+      end
+
+      # One Cargo feature per domain on disk (added when missing, never removed), with `default`
+      # set to this run's domain so a bare `cargo build` builds it. A feature is inserted right
+      # after `default = [...]`, not appended: past `[[bin]]` it would parse into that table.
+      def sync_cargo_features
+        path = File.join(@rust_dir, "Cargo.toml")
+        manifest = File.read(path)
+        manifest = manifest.sub(/\A/, FEATURES_HEADER) unless manifest.include?("[features]")
+        @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)
+          puts "wrote #{path} (default feature: #{@mod_name})"
+        else
+          puts "#{path} unchanged (default feature already #{@mod_name})"
+        end
+      end
+
+      # Checked against the `[features]` table only: `[package]`'s `name` or a `[[bin]]` path can
+      # share a word with a domain name.
+      def add_feature(manifest, name)
+        table = manifest[/^\[features\](?:\n(?!\[).*)*$/] || ""
+        return manifest if table =~ /^#{Regexp.escape(name)}\s*=/
+
+        manifest.sub(/^default\s*=.*$/) { "#{Regexp.last_match(0)}\n#{name} = []" }
+      end
+
+      FEATURES_HEADER = <<~TOML
+        # One feature per generated domain: it selects which domain's own
+        # generated::<domain>::merged module `generated::active` re-exports
+        # (rust/src/generated/mod.rs). `hecks project_rust` adds a feature when a new domain is
+        # generated and never removes one (the domain's own generated/<name>/ directory is the
+        # source of truth for whether it exists). `default` tracks the domain generated most
+        # recently, so a bare `cargo build` keeps working; any other still-generated domain stays
+        # reachable via `--no-default-features --features <name>`.
+        [features]
+        default = []
+
+      TOML
+      private_constant :FEATURES_HEADER
+    end
+  end
+end
+
+require_relative "project_rust/root_mod"