hecks 5.0.0 → 7.0.0

data/lib/hecks/rust_build/prebuilt_binary.rb

@@ -10,13 +10,13 @@ module Hecks
   module RustBuild
     # A binary hecks has already compiled and published, named by what went into it (ADR 0110).
     #
-    # The `PrebuiltBinary` rows of the Vocabulary chapter say which binaries are published: the
+    # The `PrebuiltBinary` rows of the Vocabulary bluebook say which binaries are published: the
     # crate to key, the Cargo binary, the target it is built for. A release tagged `<name>-<key>`
     # holds the binary and its `.sha256`; the key is a hash of the crate's build inputs, so the
     # same bytes are the same release, whichever commit they come from. `fetch` downloads it and
     # checks its hash, and answers nil on any miss (not published yet, no network, a hash that
-    # does not match) so a caller compiles as it always did. `HECKS_PREBUILT=off` turns the
-    # download off.
+    # does not match) so a caller compiles as it always did. `--no-prebuilt` on the host build
+    # turns the download off.
     module PrebuiltBinary
       # Where releases are published.
       REPOSITORY = "heckslabs/hecks"
@@ -36,6 +36,26 @@ module Hecks
           raise KeyError, "no PrebuiltBinary row named #{name.inspect}"
       end
 
+      # @param crate [String] a row's crate, the directory under the checkout (`rust/host`)
+      # @param target [String] the triple the caller builds for
+      # @return [String, nil] the name of the row that publishes the crate for the target,
+      #   nil when none does
+      def name_for(crate, target)
+        found = Hecks::Vocabulary.rows("PrebuiltBinary").find { |row| row["crate"] == crate && row["target"] == target }
+        found&.fetch("name")
+      end
+
+      # @param crate [String] a row's crate
+      # @param crate_dir [String] the crate's directory
+      # @param target [String] the triple the caller builds for
+      # @param into [String] the file to write the binary to
+      # @return [String, nil] `into`, or nil when no row publishes the crate for the target
+      #   or `fetch` misses
+      def fetch_for(crate, crate_dir, target:, into:, allowed: true)
+        name = name_for(crate, target) or return
+        fetch(name, crate_dir, target: target, into: into, allowed: allowed)
+      end
+
       # @param crate_dir [String] the crate's directory
       # @return [String] a hash of every file that goes into the build: each path and its bytes, in
       #   path order, so it does not depend on the checkout it is read from
@@ -66,8 +86,8 @@ module Hecks
       # @param into [String] the file to write the binary to
       # @return [String, nil] `into`, or nil when the binary is not published for this target or
       #   could not be fetched and verified
-      def fetch(name, crate_dir, target:, into:)
-        return if ENV["HECKS_PREBUILT"] == "off" || row(name)["target"] != target
+      def fetch(name, crate_dir, target:, into:, allowed: true)
+        return if !allowed || row(name)["target"] != target
 
         body = verified(name, crate_dir) or return
         FileUtils.mkdir_p(File.dirname(into))

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

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "json"
+require "open3"
 require "tmpdir"
 require_relative "../write_if_changed"
 
@@ -14,8 +15,8 @@ module Hecks
       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)
+        # One bluebook's IR, generated into its own module.
+        Declaration = 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
@@ -41,14 +42,14 @@ module Hecks
 
         # @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:)
+        # @param target [Declaration, nil] the domain being projected; nil for a run of `meta` alone
+        # @param declarations [Array<Declaration>] every other bluebook the target attached
+        # @param meta [Hash, nil] the self-hosted language's IR; nil leaves `meta` as it is on disk
+        def initialize(rust_dir:, out_root:, meta: nil, target: nil, declarations: [])
           @rust_dir = rust_dir
           @out_root = out_root
           @target = target
-          @chapters = chapters
+          @declarations = declarations
           @meta = meta
         end
 
@@ -59,19 +60,50 @@ module Hecks
           Dir.mktmpdir("hecks-codegen-full") do |tmp|
             stage = File.join(tmp, "generated")
             FileUtils.mkdir_p(stage)
-            generate_meta(stage, tmp)
-            generate_target(stage, tmp)
+            generate_meta(stage, tmp) if @meta
+            generate_target(stage, tmp) if @target
             sync(stage)
           end
         end
 
+        # Builds the binary once, then holds the build as done while the block runs. Each `cargo
+        # build` replaces the binary with a fresh link, so children forked to generate side by side
+        # would each leave a moment when a sibling finds no binary to start; the parent builds
+        # instead, before the fork, and the children skip it.
+        #
+        # @param rust_dir [String] the workspace being generated into
+        # @yield the work that forks the children
+        # @return [Object] the block's value
+        # @raise [Failure] when `hecks-codegen` cannot be built
+        def self.prebuilt(rust_dir)
+          dir = crate_dir(rust_dir)
+          build(dir)
+          @prebuilt = dir
+          yield
+        ensure
+          @prebuilt = nil
+        end
+
+        # @param dir [String] the `hecks-codegen` crate's directory
+        # @return [Boolean] whether a parent process built it for the children it forked
+        def self.prebuilt?(dir) = @prebuilt == dir
+
+        # @param dir [String] the `hecks-codegen` crate's directory
+        # @return [void]
+        # @raise [Failure] when Cargo cannot build it
+        def self.build(dir)
+          output, status = Open3.capture2e("cargo", "build", "--quiet", chdir: dir)
+          $stdout.write(output)
+          return if status.success?
+
+          raise Failure, "hecks project_rust: cargo build failed in #{dir} — run it there directly to see why"
+        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"
+          self.class.build(dir) unless self.class.prebuilt?(dir)
         end
 
         def generate_meta(stage, tmp)
@@ -81,8 +113,8 @@ module Hecks
 
         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))
+          @declarations.each do |declaration|
+            args.push(declaration.mod_name, declaration.label, write_ir(tmp, declaration.mod_name, declaration.ir))
           end
           run("full", *args)
         end
@@ -113,9 +145,11 @@ module Hecks
         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"))
+          texts = Dir.children(source).sort.to_h do |file|
+            [File.join(dest, file), File.read(File.join(source, file), encoding: "UTF-8")]
+          end
+          RustFormat.files(texts).each do |path, text|
+            wrote = WriteIfChanged.call(path, text, formatted: true, atomic: true)
             puts(wrote ? "wrote #{path}" : "#{path} unchanged")
           end
         end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # The corpus's declared domains, which a corpus run hands every `hecks project_rust` it
+      # makes. Given them, a run writes `mod.rs` and Cargo's features for exactly these domains and
+      # leaves Cargo's `default` on `default`, so what a domain generates does not depend on which
+      # domains ran before it. Without them (a workspace of one's own) a run follows the domains on
+      # disk and points `default` at the domain it generated.
+      #
+      # A run that regenerates only some of the declared domains says so with `--partial`. It writes
+      # those domains and leaves `mod.rs` and Cargo's features to a run of the whole corpus: the
+      # bluebooks `mod.rs` lists are the ones on disk, so a few domains' run would drop the rest.
+      #
+      #   hecks project_rust examples/pizzas --declared=banking,pizzas --default=pizzas --partial
+      class Declared
+        # The flag naming the declared domains, comma-separated.
+        DOMAINS_FLAG = "--declared="
+        # The flag naming the declared feature Cargo's `default` stays on.
+        DEFAULT_FLAG = "--default="
+        # The flag saying this run is one of some, not of the whole corpus.
+        PARTIAL_FLAG = "--partial"
+
+        # @return [Array<String>] the declared domains' feature names
+        attr_reader :domains
+        # @return [String] the one of them Cargo's `default` stays on
+        attr_reader :default
+
+        # Takes the declared flags out of a command line.
+        #
+        # @param argv [Array<String>] the arguments of `hecks project_rust`
+        # @return [Array(Declared, Array<String>), Array(nil, Array<String>)] what the flags
+        #   declared (nil when there are none) and the arguments left
+        # @raise [Failure] when one flag is given without the other, or `default` is not declared
+        def self.split(argv)
+          flags, rest = argv.partition { |arg| arg.start_with?(DOMAINS_FLAG, DEFAULT_FLAG) || arg == PARTIAL_FLAG }
+          return [nil, rest] if flags.empty?
+
+          [read(flags), rest]
+        end
+
+        # @param flags [Array<String>] the declared flags of a command line
+        # @return [Declared] what they declare
+        # @raise [Failure] when one flag is given without the other, or `default` is not declared
+        def self.read(flags)
+          domains = value(flags, DOMAINS_FLAG)&.split(",")
+          default = value(flags, DEFAULT_FLAG)
+          unless domains && default && domains.include?(default)
+            raise Failure, "hecks project_rust: #{DOMAINS_FLAG}<a,b,...> and #{DEFAULT_FLAG}<one of them> go together"
+          end
+
+          new(domains, default, partial: flags.include?(PARTIAL_FLAG))
+        end
+
+        def self.value(flags, flag)
+          flags.find { |arg| arg.start_with?(flag) }&.delete_prefix(flag)
+        end
+        private_class_method :value, :read
+
+        # @param domains [Array<String>] the declared domains' feature names
+        # @param default [String] the declared domain Cargo's `default` stays on
+        # @param partial [Boolean] whether this run generates only some of them
+        def initialize(domains, default, partial: false)
+          @domains = domains
+          @default = default
+          @partial = partial
+        end
+
+        # @return [Boolean] whether this run leaves `mod.rs` and Cargo's features to a whole run
+        def partial? = @partial
+
+        # @return [Array<String>] the flags that declare these domains to `hecks project_rust`
+        def flags
+          ["#{DOMAINS_FLAG}#{domains.join(",")}", "#{DEFAULT_FLAG}#{default}", *(PARTIAL_FLAG if partial?)]
+        end
+      end
+    end
+  end
+end

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

@@ -10,6 +10,9 @@ module Hecks
         FRAMEWORK_FILES = %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
                              adapters/driven/prism.adapter adapters/driven/postgres_era.adapter].freeze
 
+        # A `runs` line in an `.adapter` file: the adapter is a wasm plugin.
+        RUNS_LINE = /^\s*runs\s/
+
         # @return [Hecks::Runtime::Registry] the registry the domain was loaded into
         attr_reader :registry
 
@@ -26,7 +29,7 @@ module Hecks
         end
 
         # `root:` is the domain's own directory: a domain that declares `attaches ... from: :vendor`
-        # resolves its vendored chapters beneath it.
+        # resolves its vendored bluebooks beneath it.
         #
         # @return [DomainLoader] self, with the registry loaded
         def call
@@ -35,6 +38,7 @@ module Hecks
             load_framework
             Hecks::Adapters::Folder.new.load_bluebooks(@bluebook_dir)
             load_siblings
+            load_plugins
             load_environment
           end
           @domain_name = @registry.bluebooks.keys.first
@@ -48,7 +52,7 @@ module Hecks
           FRAMEWORK_FILES.each { |file| Kernel.load(File.join(lib, file)) }
         end
 
-        # Translation edges, hecksagons (whose `attaches` loads a framework chapter into the
+        # Translation edges, hecksagons (whose `attaches` loads a framework bluebook 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
@@ -57,6 +61,15 @@ module Hecks
           Dir.glob(File.join(@bluebook_dir, "*.world")).each { |file| Kernel.load(file) }
         end
 
+        # The domain's own wasm plugins, so the IR carries them to the host: only an `.adapter`
+        # that `runs` a module, since the build needs no Ruby adapter and its code may need gems
+        # the build does not have. A vendored package's plugins load with its bluebook.
+        def load_plugins
+          Dir.glob(File.join(@bluebook_dir, "{,adapters/}*.adapter")).each do |file|
+            Kernel.load(file) if File.read(file).match?(RUNS_LINE)
+          end
+        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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # What a Cargo manifest with no `[features]` table is given in front of its text.
+      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

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "../write_if_changed"
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # The two files every domain's generation shares: `src/generated/mod.rs` and the workspace's
+      # `Cargo.toml` features. A run of one domain writes them after its own files; a corpus run
+      # that generates its domains side by side tells each `--partial` and writes them once, here,
+      # after the last domain is done, so no two processes ever write them.
+      class Manifest
+        # The `default = [...]` line of a Cargo manifest's `[features]` table.
+        DEFAULT_FEATURE = /^default\s*=.*$/
+        # The `[features]` table of a Cargo manifest, up to the next table header.
+        FEATURES_TABLE = /^\[features\](?:\n(?!\[).*)*$/
+
+        # @param rust_dir [String] the workspace, which holds `Cargo.toml` and `src/generated`
+        # @param declared [Declared, nil] the corpus's declared domains; nil follows the domains on
+        #   disk
+        # @param default [String] the feature `mod.rs` treats as the default and Cargo's `default`
+        #   points at
+        def initialize(rust_dir, declared, default)
+          @rust_dir = rust_dir
+          @out_root = File.join(rust_dir, "src/generated")
+          @declared = declared
+          @default = default
+        end
+
+        # Writes `mod.rs` and syncs Cargo's features, each only when its bytes change.
+        #
+        # @return [void]
+        def call
+          write_root_mod
+          sync_cargo_features
+        end
+
+        private
+
+        # `src/generated/mod.rs`. A directory is a selectable domain exactly when it carries its own
+        # `merged.rs`; a framework bluebook has none and is always compiled in. The domains are
+        # scanned off disk, or, for the corpus, taken from its declared list.
+        def write_root_mod
+          all_dirs = generated_directories
+          @domains = domains_among(all_dirs)
+          path = File.join(@out_root, "mod.rs")
+          wrote = WriteIfChanged.block(path) do |file|
+            RootMod.new(file, all_dirs, @domains, @default).write
+          end
+          puts(wrote ? "wrote #{path}" : "#{path} unchanged")
+        end
+
+        # Every directory under `src/generated`. Under a declared list, its domains are named
+        # even when not generated here yet, and a leftover domain directory it does not declare is
+        # dropped.
+        def generated_directories
+          dirs = Dir.children(@out_root).select { |name| File.directory?(File.join(@out_root, name)) }
+          return dirs.sort unless @declared
+
+          bluebooks = dirs.reject { |name| File.exist?(File.join(@out_root, name, "merged.rs")) }
+          (bluebooks | @declared.domains).sort
+        end
+
+        def domains_among(directories)
+          return @declared.domains.sort if @declared
+
+          directories.select { |name| File.exist?(File.join(@out_root, name, "merged.rs")) }
+        end
+
+        # One Cargo feature per domain (added when missing, never removed), with `default` set to
+        # the default feature 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 = "#{FEATURES_HEADER}#{manifest}" unless manifest.include?("[features]")
+          @domains.each { |name| manifest = add_feature(manifest, name) }
+          manifest = manifest.sub(DEFAULT_FEATURE, "default = [#{@default.inspect}]")
+          # An unchanged manifest is not rewritten: a new mtime makes Cargo rebuild the whole crate.
+          return puts("#{path} unchanged (default feature already #{@default})") unless WriteIfChanged.call(path, manifest)
+
+          puts "wrote #{path} (default feature: #{@default})"
+        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_TABLE] || ""
+          return manifest if table =~ /^#{Regexp.escape(name)}\s*=/
+
+          manifest.sub(DEFAULT_FEATURE) { "#{Regexp.last_match(0)}\n#{name} = []" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../../bluebook/meta_validator"
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # The self-hosted language's Rust, `src/generated/meta`. It is generated from the grammar
+      # registry alone, so it is the same whichever domain a run projects: a corpus run generates it
+      # once here and tells each of its `hecks project_rust` children to skip it (`SKIP_FLAG`),
+      # instead of every child writing the identical files again.
+      module Meta
+        # The flag telling a `hecks project_rust` run that `meta` is already generated.
+        SKIP_FLAG = "--skip-meta"
+
+        # @return [Hash] the self-hosted language's IR, shaped for `hecks-codegen`
+        def self.ir
+          bluebook = Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
+          TargetIr.json_shaped(bluebook)
+        end
+
+        # Generates `meta` into the workspace, writing only the files whose bytes changed.
+        #
+        # @param rust_dir [String] the workspace being generated into
+        # @return [void]
+        # @raise [Failure] when `hecks-codegen` cannot be built or exits non-zero
+        def self.generate(rust_dir = RustBuild.rust_dir)
+          out_root = File.join(rust_dir, "src/generated")
+          FileUtils.mkdir_p(out_root)
+          CodegenRun.new(rust_dir: rust_dir, out_root: out_root, meta: ir).call
+        end
+      end
+    end
+  end
+end

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

@@ -18,7 +18,7 @@ module Hecks
             "// 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",
+            "// bluebook (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`."

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

@@ -9,9 +9,9 @@ module Hecks
       # facts, so `bluebook.to_h` never mentions them).
       class TargetIr
         # 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 checkout].freeze
+        # attached provides it: exporter method, then the key it is written under. `provides`
+        # holds every capability a package declares, by name.
+        SEAMS = %i[authorization membership identity provides].freeze
 
         # Round-trips a value through JSON so generators see the string-keyed shape a real
         # `ir.json` carries, never live Ruby symbols.
@@ -39,6 +39,7 @@ module Hecks
           add_persistence_wiring(ir, exporter)
           add_seams(ir, exporter)
           add_edges_and_source(ir)
+          add_plugins(ir, exporter)
           ir
         end
 
@@ -52,6 +53,14 @@ module Hecks
 
         def shaped(payload) = self.class.json_shaped(payload)
 
+        # The wasm plugins the host runs for queries no hecksagon binds; none, no key.
+        #
+        # @return [void]
+        def add_plugins(document, exporter)
+          plugins = exporter.plugins(@registry)
+          document[:plugins] = shaped(plugins) unless plugins.empty?
+        end
+
         # The bound persistence adapters' declarations, from the `.adapter` files under the
         # source root's `lib/` and the domain's own directory, so the host can look them up.
         def adapters(exporter, persistence)

data/lib/hecks/rust_build/project_rust.rb

@@ -22,18 +22,28 @@ module Hecks
     # 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.
     class ProjectRust
-      # @param argv [Array<String>] the domain's directory
+      # @param argv [Array<String>] the domain's directory, then optionally the corpus run's
+      #   `Declared` flags
       # @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
+        skip_meta, argv = argv.partition { |arg| arg == Meta::SKIP_FLAG }
+        declared, rest = Declared.split(argv)
+        domain = rest.first or raise Failure, "usage: hecks project_rust <domain>"
+        new(domain, declared: declared, meta: skip_meta.empty?).call
       end
 
       # @param domain [String] the domain's directory
-      def initialize(domain)
+      # @param declared [Declared, nil] the corpus's declared domains; nil for a workspace of one's
+      #   own, where `mod.rs` and Cargo's features follow the domains on disk and `default` the
+      #   domain this run generated
+      # @param meta [Boolean] whether this run generates `meta`; a corpus run that has done so once
+      #   says `Meta::SKIP_FLAG` to each domain
+      def initialize(domain, declared: nil, meta: true)
         @domain = domain
         @mod_name = File.basename(domain)
+        @declared = declared
+        @meta = meta
       end
 
       # @return [Integer] the exit status
@@ -66,12 +76,13 @@ module Hecks
         @ir = TargetIr.new(@registry, @domain_name, loader.bluebook_dir).call
         FileUtils.rm_rf(File.join(@out_root, "active"))
         generate_with_codegen
-        write_root_mod
-        sync_cargo_features
+        return puts("mod.rs and Cargo.toml left to a run of the whole corpus (--partial)") if @declared&.partial?
+
+        Manifest.new(@rust_dir, @declared, default_feature).call
       end
 
       def prepare_output
-        @rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(RustBuild::ROOT, "rust"))
+        @rust_dir = RustBuild.rust_dir
         @out_root = File.join(@rust_dir, "src/generated")
         FileUtils.mkdir_p(@out_root)
       end
@@ -79,86 +90,33 @@ module Hecks
       # `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")
         CodegenRun.new(
-          rust_dir: @rust_dir, out_root: @out_root, meta: TargetIr.json_shaped(meta), chapters: chapters,
-          target: CodegenRun::Chapter.new(@mod_name, @domain, @ir)
+          rust_dir: @rust_dir, out_root: @out_root, meta: (Meta.ir if @meta), declarations: declarations,
+          target: CodegenRun::Declaration.new(@mod_name, @domain, @ir)
         ).call
       end
 
-      def chapters
-        vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
+      # A declaration is labelled by its own name: its files read the same whoever attached it, so
+      # regenerating one domain never changes what another domain's files contain.
+      def declarations
         (@registry.bluebooks.keys - [@domain_name]).map do |name|
           ir = Hecks::Projector::Exporter.call(@registry).fetch(name)
-          label = "#{@domain} (#{attachment(name, vendored)})"
-          CodegenRun::Chapter.new(name.downcase, label, TargetIr.json_shaped(ir))
+          CodegenRun::Declaration.new(name.downcase, name, TargetIr.json_shaped(ir))
         end
       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 ? "attaches #{name.inspect}, from: :vendor" : "attaches #{chapter_name.inspect}"
-      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 = 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 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
+      # The feature `default` points at, and the one `mod.rs` treats as the default: the corpus's
+      # fixed one, else the domain this run generated.
+      def default_feature = @declared ? @declared.default : @mod_name
     end
   end
 end
 
+require_relative "project_rust/declared"
+require_relative "project_rust/features_header"
 require_relative "project_rust/root_mod"
 require_relative "project_rust/codegen_run"
+require_relative "project_rust/meta"
 require_relative "project_rust/domain_loader"
 require_relative "project_rust/target_ir"
+require_relative "project_rust/manifest"