hecks 3.5.0 → 3.7.0

data/lib/hecks/rust_build/coverage_parts/expected.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    module Coverage
+      # The [kind, id] pairs a generated module's `ir.json` implies, independent of its manifest.
+      module Expected
+        module_function
+
+        # @param payload [Hash] the parsed `ir.json`
+        # @return [Array<Array(Symbol, String)>] every construct the IR declares, as [kind, id]
+        def from_ir(payload)
+          domain_name = payload.fetch(:name)
+          expected = payload.fetch(:aggregates).flat_map { |aggregate| aggregate_constructs(domain_name, aggregate) }
+          expected.concat(named_constructs(payload, domain_name))
+          # An `ir.json` from before the `lineage` key existed has none: nothing to expect.
+          payload.fetch(:lineage, {}).fetch(:capable_aggregates, []).each do |aggregate|
+            expected << [:lineage_aggregate, "#{domain_name}::#{aggregate.fetch(:name)}"]
+          end
+          expected
+        end
+
+        # Read models, policies and process managers: constructs named directly under the domain.
+        def named_constructs(payload, domain_name)
+          { read_models: :read_model, policies: :policy, process_managers: :process_manager }.flat_map do |key, kind|
+            payload.fetch(key).map { |entry| [kind, "#{domain_name}::#{entry.fetch(:name)}"] }
+          end
+        end
+
+        # Entity-scoped query ids at any depth (`Domain::Aggregate.Entity.Query`); mirrors the
+        # generator's own entity query entries.
+        def entity_query_ids(owner_id, entities)
+          entities.flat_map do |entity|
+            entity_id = "#{owner_id}.#{entity.fetch(:name)}"
+            entity.fetch(:queries, []).map { |q| "#{entity_id}.#{q.fetch(:name)}" } +
+              entity_query_ids(entity_id, entity.fetch(:entities, []))
+          end
+        end
+
+        def aggregate_constructs(domain_name, aggregate)
+          id = "#{domain_name}::#{aggregate.fetch(:name)}"
+          [[:aggregate, id]] + owned_constructs(id, aggregate) + entity_constructs(id, aggregate) +
+            port_operations(id, aggregate)
+        end
+
+        def owned_constructs(id, aggregate)
+          aggregate.fetch(:commands).map { |c| [:command, "#{id}.#{c.fetch(:name)}"] } +
+            aggregate.fetch(:queries).map { |q| [:query, "#{id}.#{q.fetch(:name)}"] } +
+            entity_query_ids(id, aggregate.fetch(:entities)).map { |query_id| [:query, query_id] }
+        end
+
+        def entity_constructs(id, aggregate)
+          aggregate.fetch(:entities).flat_map do |entity|
+            entity_id = "#{id}.#{entity.fetch(:name)}"
+            [[:entity, entity_id]] +
+              entity.fetch(:commands).map { |c| [:entity_command, "#{entity_id}.#{c.fetch(:name)}"] }
+          end
+        end
+
+        def port_operations(id, aggregate)
+          aggregate.fetch(:ports).flat_map do |port|
+            port.fetch(:operations).map { |op| [:port_operation, "#{id}.#{port.fetch(:name)}.#{op.fetch(:name)}"] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/coverage_parts/printer.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    module Coverage
+      # Prints a coverage report: the implemented, deferred and gap buckets of a module's findings.
+      module Printer
+        module_function
+
+        # @param domain [String] the generated module's name
+        # @param name [String] the domain's name from its `ir.json`
+        # @param findings [Array<Hash>] the manifest entries plus synthetic `unaccounted` ones
+        # @param allowlist [#call] answers the allowlist rule excusing a finding, or nil
+        # @return [Integer] 0 when no gap remains, 1 otherwise
+        def report(domain, name, findings, allowlist)
+          implemented, deferred, gap = buckets(findings, allowlist)
+          banner(domain)
+          puts summary(name, findings.size, [implemented, deferred, gap])
+          print_bucket("IMPLEMENTED", implemented) unless implemented.empty?
+          print_deferred(deferred, allowlist)
+          print_gaps(gap)
+          puts
+          gap.empty? ? 0 : 1
+        end
+
+        # A construct is implemented only when generated and routed (where routing applies): a
+        # `dispatch_*` that compiles but nothing can call is not working.
+        def buckets(findings, allowlist)
+          implemented, remainder = findings.partition { |f| f[:generated] && f[:routed] != false }
+          deferred, gap = remainder.partition { |f| allowlist.call(f) }
+          [implemented, deferred, gap]
+        end
+
+        def summary(name, total, buckets)
+          implemented, deferred, gap = buckets.map(&:size)
+          "#{name} — #{total} constructs accounted for " \
+            "(#{implemented} implemented, #{deferred} deferred, #{gap} GAP)"
+        end
+
+        def banner(domain)
+          puts "=" * 72
+          puts "hecks rust_coverage #{domain}  (source: manifest.json)"
+          puts "=" * 72
+        end
+
+        def print_bucket(label, entries)
+          puts "\n#{label} (#{entries.size})"
+          sorted(entries).each { |entry| print_entry(entry) }
+        end
+
+        def print_deferred(deferred, allowlist)
+          puts "\nDEFERRED (#{deferred.size}) — on the allowlist, with its cited reason"
+          sorted(deferred).each do |entry|
+            puts "  [#{entry[:kind]}] #{entry[:id]}"
+            puts "      allowlist: #{allowlist.call(entry)[:doc]}"
+          end
+        end
+
+        def print_gaps(gap)
+          puts "\nGAP (#{gap.size}) — missing, and NOT on the allowlist: a real, actionable finding"
+          sorted(gap).each { |entry| print_entry(entry) }
+        end
+
+        def print_entry(entry)
+          line = "  [#{entry[:kind]}] #{entry[:id]}"
+          line += " (#{entry[:gap_class]})" if entry[:gap_class]
+          puts line
+          puts "      #{entry[:reason]}" if entry[:reason]
+        end
+
+        def sorted(entries) = entries.sort_by { |entry| [entry[:kind].to_s, entry[:id]] }
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/host.rb

@@ -40,14 +40,15 @@ module Hecks
         require_buildable!(target)
         stage = flag(argv, "stage") || File.join(Dir.pwd, ".hecks", "host", target)
 
-        status = Wasm.call([domain])
-        raise Failure, "project_wasm failed for #{domain}" unless status.zero?
-
-        binary = compile(target)
-        publish(binary, File.basename(domain.chomp("/")), stage)
+        build_module(domain)
+        publish(compile(target), File.basename(domain.chomp("/")), stage)
         0
       end
 
+      def build_module(domain)
+        raise Failure, "project_wasm failed for #{domain}" unless Wasm.call([domain]).zero?
+      end
+
       # @param argv [Array<String>] a tool's arguments
       # @param name [String] a flag's name
       # @return [String, nil] the value of `--<name>=<value>`, nil when absent
@@ -72,6 +73,10 @@ module Hecks
                          "build.build_wasm, or name a native target"
         end
 
+        require_installed!(target)
+      end
+
+      def require_installed!(target)
         require_rustup!
         installed = query("rustup", "target", "list", "--installed", "--toolchain", TOOLCHAIN).to_s.split
         return if installed.include?(target) || target == host_triple
@@ -107,10 +112,10 @@ module Hecks
       end
 
       def linker_for(target)
-        variable = "CARGO_TARGET_#{target.upcase.tr('-.', '__')}_LINKER"
+        variable = "CARGO_TARGET_#{target.upcase.tr("-.", "__")}_LINKER"
         return {} if ENV.key?(variable) || target == host_triple
 
-        candidate = "#{target.split('-').first}-linux-gnu-gcc"
+        candidate = "#{target.split("-").first}-linux-gnu-gcc"
         target.end_with?("linux-gnu") && query(candidate, "--version") ? { variable => candidate } : {}
       end
 
@@ -118,21 +123,26 @@ module Hecks
         return "" if target == host_triple
 
         "\n#{target} differs from this machine's #{host_triple}, so linking needs a linker for it: " \
-          "put a cross compiler such as #{target.split('-').first}-linux-gnu-gcc on PATH, or set " \
-          "CARGO_TARGET_#{target.upcase.tr('-.', '__')}_LINKER"
+          "put a cross compiler such as #{target.split("-").first}-linux-gnu-gcc on PATH, or set " \
+          "CARGO_TARGET_#{target.upcase.tr("-.", "__")}_LINKER"
       end
 
       def publish(binary, name, stage)
-        dist = File.join(RustBuild.rust_dir, "dist")
-        files = { binary => "#{name}-host", File.join(dist, "#{name}.wasm") => "#{name}.wasm",
-                  File.join(dist, "#{name}.ir.json") => "#{name}.ir.json" }
+        files = staged_files(binary, name)
         files.each_key do |path|
           raise Failure, "the build left no #{path}" unless File.file?(path)
         end
         FileUtils.mkdir_p(stage)
         files.each { |from, to| FileUtils.cp(from, File.join(stage, to)) }
         File.chmod(0o755, File.join(stage, "#{name}-host"))
-        puts "staged in #{stage}: #{files.values.join(', ')}"
+        puts "staged in #{stage}: #{files.values.join(", ")}"
+      end
+
+      # @return [Hash{String => String}] each built file's path, to the name it is staged under
+      def staged_files(binary, name)
+        dist = File.join(RustBuild.rust_dir, "dist")
+        { binary => "#{name}-host", File.join(dist, "#{name}.wasm") => "#{name}.wasm",
+          File.join(dist, "#{name}.ir.json") => "#{name}.ir.json" }
       end
 
       # @return [String, nil] a program's combined output, nil when it is missing or fails

data/lib/hecks/rust_build/kernel_input.rb

@@ -46,7 +46,7 @@ module Hecks
         tables = { "defaults" => {}, "needs" => {}, "query_needs" => {} }
         ir = generated_ir(domain_path) or return tables
         domain = ir["name"].to_s
-        Array(ir["aggregates"]).each { |aggregate| collect(aggregate, "#{domain}::#{aggregate['name']}", tables) }
+        Array(ir["aggregates"]).each { |aggregate| collect(aggregate, "#{domain}::#{aggregate["name"]}", tables) }
         tables
       end
 
@@ -58,17 +58,24 @@ module Hecks
       # @param tables [Hash] filled in place
       # @return [void]
       def collect(node, prefix, tables)
-        Array(node["commands"]).each do |command|
-          verb = "#{prefix}.#{command['name']}"
-          held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
-                                             .to_h { |attribute| [attribute["name"], attribute["default"]] }
-          tables["defaults"][verb] = held unless held.empty?
-          tables["needs"][verb] = needs_of(command) unless Array(command["needs"]).empty?
-        end
-        Array(node["queries"]).each do |query|
-          tables["query_needs"]["#{prefix}.#{query['name']}"] = needs_of(query) unless Array(query["needs"]).empty?
-        end
-        Array(node["entities"]).each { |entity| collect(entity, "#{prefix}.#{entity['name']}", tables) }
+        Array(node["commands"]).each { |command| collect_command(command, "#{prefix}.#{command["name"]}", tables) }
+        Array(node["queries"]).each { |query| collect_query(query, "#{prefix}.#{query["name"]}", tables) }
+        Array(node["entities"]).each { |entity| collect(entity, "#{prefix}.#{entity["name"]}", tables) }
+      end
+
+      def collect_command(command, verb, tables)
+        held = defaults_of(command)
+        tables["defaults"][verb] = held unless held.empty?
+        tables["needs"][verb] = needs_of(command) unless Array(command["needs"]).empty?
+      end
+
+      def defaults_of(command)
+        Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
+                                    .to_h { |attribute| [attribute["name"], attribute["default"]] }
+      end
+
+      def collect_query(query, verb, tables)
+        tables["query_needs"][verb] = needs_of(query) unless Array(query["needs"]).empty?
       end
 
       # @param declaration [Hash] a command or query of the IR that declares `needs`

data/lib/hecks/rust_build/native_build.rb

@@ -12,6 +12,9 @@ module Hecks
     # 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.
+    #
+    # A binary already pinned and newer than every source is used as it is, so binaries restored
+    # from a cache of an earlier run are not built again.
     module NativeBuild
       # Raised when a declared feature fails to build; nil is reserved for "feature not declared".
       class BuildFailed < StandardError; end
@@ -34,23 +37,27 @@ module Hecks
       # @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 replay(NativeBuild.cache[key]) if NativeBuild.cache.key?(key)
 
-          return cache[key]
-        end
+        build_and_cache(key, domain_feature, rust_dir)
+      end
+
+      def replay(answer)
+        raise answer if answer.is_a?(BuildFailed)
 
+        answer
+      end
+
+      def build_and_cache(key, domain_feature, rust_dir)
+        cache = NativeBuild.cache
         manifest = File.read(File.join(rust_dir, "Cargo.toml"))
-        return cache[key] = nil unless manifest =~ /^#{Regexp.escape(domain_feature)}\s*=\s*\[\]/
+        return cache[key] = nil unless /^#{Regexp.escape(domain_feature)}\s*=\s*\[\]/.match?(manifest)
 
-        begin
-          cache[key] = build_and_pin(domain_feature, rust_dir)
-        rescue BuildFailed => e
-          cache[key] = e
-          raise
-        end
+        cache[key] = build_and_pin(domain_feature, rust_dir)
+      rescue BuildFailed => e
+        cache[key] = e
+        raise
       end
 
       # Fingerprints what a build reads: every `.rs`, `.toml` and `Cargo.lock` file under the
@@ -90,31 +97,56 @@ module Hecks
 
         File.open(lock_path, File::CREAT | File::RDWR) do |lock|
           lock.flock(File::LOCK_EX)
+          pinned = pinned_path(rust_dir, domain_feature)
+          next pinned if pinned_fresh?(pinned, rust_dir)
+
           command = ["cargo", "build", "--no-default-features", "--features", domain_feature]
           cargo(command, rust_dir, domain_feature)
           pin(rust_dir, domain_feature, command)
         end
       end
 
+      def pinned_path(rust_dir, domain_feature)
+        File.join(rust_dir, "target", "debug", "rust-#{domain_feature}")
+      end
+
+      # A binary pinned ahead of time, by an earlier run whose build was restored from a cache, is
+      # current when no source is newer than it: the rule `make` applies to any target.
+      #
+      # @return [Boolean] whether `pinned` exists and every source predates it
+      def pinned_fresh?(pinned, rust_dir)
+        return false unless File.executable?(pinned)
+
+        built = File.mtime(pinned)
+        source_files(rust_dir).none? { |path| File.mtime(path) > built }
+      end
+
+      # @return [Array<String>] every `.rs` and `.toml` file and `Cargo.lock` outside `target/`
+      def source_files(rust_dir)
+        paths = Dir.glob(File.join(rust_dir, "**", "*.{rs,toml}"), File::FNM_DOTMATCH)
+        paths << File.join(rust_dir, "Cargo.lock")
+        paths.select { |path| File.file?(path) && !path.delete_prefix("#{rust_dir}/").start_with?("target/") }
+      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}) — " \
+        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}"
+        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}"
+          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}")
+        pinned = pinned_path(rust_dir, domain_feature)
         FileUtils.cp(binary, pinned)
         File.chmod(0o755, pinned)
         pinned

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # Loads one domain directory into a fresh registry: its bluebooks, then its translation edges,
+      # hecksagons, worlds and environment, in the order the language loads them.
+      class DomainLoader
+        # The port and adapter declarations every domain load needs, relative to `lib/hecks`.
+        FRAMEWORK_FILES = %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
+                             adapters/driven/prism.adapter adapters/driven/postgres_era.adapter].freeze
+
+        # @return [Hecks::Runtime::Registry] the registry the domain was loaded into
+        attr_reader :registry
+
+        # @return [String] the domain's `bluebook/` directory
+        attr_reader :bluebook_dir
+
+        # @return [String] the name of the first bluebook loaded
+        attr_reader :domain_name
+
+        # @param domain [String] the domain's directory
+        def initialize(domain)
+          @domain = domain
+          @bluebook_dir = File.join(domain, "bluebook")
+        end
+
+        # `root:` is the domain's own directory: a domain that declares `attaches ... from: :vendor`
+        # resolves its vendored chapters beneath it.
+        #
+        # @return [DomainLoader] self, with the registry loaded
+        def call
+          @registry = Hecks::Runtime::Registry.new(root: File.expand_path(@domain))
+          Hecks.with_registry(@registry) do
+            load_framework
+            Hecks::Adapters::Folder.new.load_bluebooks(@bluebook_dir)
+            load_siblings
+            load_environment
+          end
+          @domain_name = @registry.bluebooks.keys.first
+          self
+        end
+
+        private
+
+        def load_framework
+          lib = File.expand_path("../..", __dir__)
+          FRAMEWORK_FILES.each { |file| Kernel.load(File.join(lib, file)) }
+        end
+
+        # 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
+          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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      class RootMod
+        # The explanatory comment blocks emitted at the top of `src/generated/mod.rs`, one entry per
+        # output line.
+        module Notes
+          BANNER = [
+            "// GENERATED by hecks project_rust — re-run it to refresh this list.",
+            "//",
+            "// BUG#25 — every DOMAIN (an entry in `domains`, below: a directory",
+            "// carrying its own merged.rs and therefore its own Cargo feature) is",
+            "// declared behind that SAME feature, so a broken or absent domain's",
+            "// generated code is never even compiled into a build that selects a",
+            "// DIFFERENT domain — `cargo build --features waybill` used to pull in",
+            "// every OTHER domain's `pub mod` unconditionally, so one domain's own",
+            "// non-compiling generated code (a `has_many` field, before this fix)",
+            "// broke every feature's build, not just its own. A shared FRAMEWORK",
+            "// chapter (governance/identity — no merged.rs of its own, so absent",
+            "// from `domains`) stays unconditional: it has no single feature of its",
+            "// own to gate behind, and is compiled in by whichever domain(s) attach",
+            "// it via `attaches`."
+          ].freeze
+
+          ACTIVE_HEAD = [
+            "// `active` is whichever ONE domain's own merged Store/dispatch table",
+            "// is selected by Cargo feature (rust/Cargo.toml, kept in sync with this",
+            "// list by hecks project_rust) — kernel/cli.rs imports",
+            "// `crate::generated::active::{dispatch_by_name, Store, ...}` unchanged",
+            "// no matter which domain that resolves to.",
+            "//",
+            "// DOMAIN FEATURES ARE MUTUALLY EXCLUSIVE (R5) — Cargo has no native"
+          ].freeze
+
+          ACTIVE_TAIL = [
+            "// Cargo.toml stays enabled unless a build passes",
+            "// `--no-default-features`, so a plain `cargo build --features banking`",
+            "// used to enable BOTH the default domain's feature and banking's,",
+            "// producing two `pub use ... as active;` imports and a hard E0252.",
+            "// Fixed two ways below, entirely mechanically from `domains`/",
+            "// `target_mod_name` (this run's new default) — never hand-maintained:",
+            "//",
+            "//   1. THE DEFAULT DOMAIN'S OWN re-export backs off whenever any OTHER",
+            "//      domain feature is also enabled, so it never contends for `active`",
+            "//      by accident — `cargo build --features banking` (still implicitly",
+            "//      carrying the default feature) now resolves to banking alone,",
+            "//      same as if `--no-default-features` had been passed explicitly.",
+            "//   2. Two NON-default domain features enabled TOGETHER (a genuine,",
+            "//      not-accidental conflict — nothing makes that combination",
+            "//      meaningful) still fail the build, but with an explicit",
+            "//      `compile_error!` naming both features instead of a cryptic",
+            "//      \"defined multiple times\"."
+          ].freeze
+
+          # @param default [String] the domain whose feature `default` names in Cargo.toml
+          # @return [Array<String>] the lines explaining how `active` is selected
+          def self.active(default)
+            ACTIVE_HEAD + ["// concept of that, and `default = [#{default.inspect}]` in"] + ACTIVE_TAIL
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "root_mod/notes"
+
 module Hecks
   module RustBuild
     class ProjectRust
@@ -30,20 +32,7 @@ module Hecks
         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 `attaches`."
+          @file.puts Notes::BANNER
         end
 
         def modules
@@ -55,31 +44,7 @@ module Hecks
 
         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\"."
+          @file.puts Notes.active(@default)
         end
 
         def reexports
@@ -97,22 +62,24 @@ module Hecks
 
         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
+          return unless 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 { |first, second| conflict_guard(first, second) }
+        end
+
+        def conflict_guard(first, second)
+          @file.puts "#[cfg(all(feature = #{first.inspect}, feature = #{second.inspect}))]"
+          # Plain `first`/`second`/`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 #{first} and #{second} are enabled)\");"
         end
       end
     end