hecks 3.2.0 → 3.2.1

data/lib/hecks/rust_build/kernel_input.rb

@@ -30,7 +30,8 @@ module Hecks
       # @return [String] the input as JSON, ready for the binary's stdin
       def json(domain_path, steps) = JSON.generate(build(domain_path, steps))
 
-      # Each command's declared defaults, read from the domain's generated IR.
+      # Each command's declared defaults, entity commands included, read from the domain's
+      # generated IR. An entity's commands sit under `Domain::Aggregate.Entity[.Entity].Command`.
       #
       # @param domain_path [String] the domain's directory
       # @return [Hash{String => Hash{String => Object}}] empty when the IR is absent or has none
@@ -38,14 +39,25 @@ module Hecks
         ir = generated_ir(domain_path) or return {}
         domain = ir["name"].to_s
         Array(ir["aggregates"]).each_with_object({}) do |aggregate, table|
-          Array(aggregate["commands"]).each do |command|
-            held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
-                                               .to_h { |attribute| [attribute["name"], attribute["default"]] }
-            table["#{domain}::#{aggregate['name']}.#{command['name']}"] = held unless held.empty?
-          end
+          collect_defaults(aggregate, "#{domain}::#{aggregate['name']}", table)
         end
       end
 
+      # Adds the defaults of `node`'s commands, then of each entity nested in it, under `prefix`.
+      #
+      # @param node [Hash] an aggregate or entity of the IR
+      # @param prefix [String] the verb path down to `node`
+      # @param table [Hash] filled in place
+      # @return [void]
+      def collect_defaults(node, prefix, table)
+        Array(node["commands"]).each do |command|
+          held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
+                                             .to_h { |attribute| [attribute["name"], attribute["default"]] }
+          table["#{prefix}.#{command['name']}"] = held unless held.empty?
+        end
+        Array(node["entities"]).each { |entity| collect_defaults(entity, "#{prefix}.#{entity['name']}", table) }
+      end
+
       # @param domain_path [String] the domain's directory
       # @return [Hash, nil] the parsed generated IR, or nil when the domain has none
       def generated_ir(domain_path)

data/lib/hecks/rust_build/project_rust.rb

@@ -17,9 +17,8 @@ module Hecks
     #   ProjectRust.call(["path/to/domain"])
     #
     # `hecks-codegen` is the generator (ADR 0086): this class builds the IR from the live registry
-    # and `CodegenRun` runs the binary on it. `HECKS_CODEGEN=ruby` selects the Ruby generator in
-    # `rust/project` until that is deleted; `HECKS_PARSER=rust` with `HECKS_CODEGEN=rust` runs
-    # `rust/project_rust_pipeline.rb` instead, with no Ruby load of the domain.
+    # and `CodegenRun` runs the binary on it. The Ruby-free path is `hecks-build`, which feeds the
+    # same binary from `hecks-parse`.
     #
     # 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.
@@ -46,13 +45,7 @@ module Hecks
       # @return [Integer] the exit status
       def call
         validate_name!
-        if ENV["HECKS_PARSER"] == "rust" && ENV["HECKS_CODEGEN"] == "rust"
-          require_relative "../../../rust/project"
-          require_relative "../../../rust/project_rust_pipeline"
-          RustProjectPipeline.call(@domain)
-        else
-          generate
-        end
+        generate
         0
       end
 
@@ -78,18 +71,11 @@ module Hecks
         FileUtils.mkdir_p(@out_root)
         build_target_ir
         FileUtils.rm_rf(File.join(@out_root, "active"))
-        ENV["HECKS_CODEGEN"] == "ruby" ? generate_with_ruby : generate_with_codegen
+        generate_with_codegen
         write_root_mod
         sync_cargo_features
       end
 
-      # The rollback path (ADR 0086): the Ruby generator in `rust/project`, until it is deleted.
-      def generate_with_ruby
-        require_relative "../../../rust/project"
-        write_meta
-        write_target
-      end
-
       # `hecks-codegen` is the generator; this process only builds the IR it reads from the live
       # registry, so a domain's persistence, seams, translations and source text reach `ir.json`.
       def generate_with_codegen
@@ -105,8 +91,8 @@ module Hecks
         ).call
       end
 
-      # The IR as `rust/project` hands it to its generators: string-keyed through JSON, with the
-      # append-optional fields marked, since `ir.json` records them.
+      # The IR as the generator reads it: string-keyed through JSON, with the append-optional
+      # fields marked, since `ir.json` records them.
       def prepared_ir(tree, shaped: true)
         AppendOptionals.mark(shaped ? json_shaped(tree) : tree)
       end
@@ -186,78 +172,6 @@ module Hecks
         )
       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.
-        WriteIfChanged.push_directory(dir)
-        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"))
-        WriteIfChanged.pop_and_prune(dir)
-      end
-
-      def write_target
-        dir = File.join(@out_root, @mod_name)
-        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"))
-        WriteIfChanged.pop_and_prune(dir)
-      end
-
-      # Every other bluebook the target's `attaches` calls pulled into the registry, each
-      # generated into its own module. A framework chapter is a function of its bluebook alone, so
-      # regenerating one is safe whichever domain last touched it.
-      def write_chapters
-        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_packages)
-        (@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
-        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)
@@ -265,46 +179,6 @@ module Hecks
         name ? "attaches #{name.inspect}, from: :vendor" : "attaches #{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 = 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.

data/lib/hecks/site/bluebook/site.bluebook

@@ -95,12 +95,14 @@ Hecks.bluebook "Site" do
   aggregate "SiteProjection" do
     description "One projection of a site's route table into its routes.ts, or the check that the file on disk is current."
 
-    attribute :domain,  DomainPath
-    attribute :run,     RunKey
-    attribute :out,     Location, optional: true
-    attribute :check,   Switch,   optional: true
-    attribute :output,  Report,   optional: true
-    attribute :refusal, Report,   optional: true
+    attribute :domain,    DomainPath
+    attribute :run,       RunKey
+    attribute :out,       Location,  optional: true
+    attribute :template,  Location,  optional: true
+    attribute :extension, Extension, optional: true
+    attribute :check,     Switch,    optional: true
+    attribute :output,    Report,    optional: true
+    attribute :refusal,   Report,    optional: true
     identified_by :run
 
     value_object "RunKey" do
@@ -116,11 +118,18 @@ Hecks.bluebook "Site" do
       invariant("a project is named by its path") { !value.to_s.empty? }
     end
 
-    # Where routes.ts is written, when not beside the project's bluebook.
+    # A directory or file anywhere on disk, relative to where the command runs: where routes.ts is
+    # written when not in the project's generated/ directory, or the template to rewrite in place.
     value_object "Location" do
       attribute :value, String, pattern: '[^\t\n\r]'
     end
 
+    # The file extension of the generated module: `ts` (routes.ts), or `mts` (routes.mts), which
+    # Node loads as an ES module even in a package whose "type" is "commonjs".
+    value_object "Extension" do
+      attribute :value, String, one_of: ["ts", "mts"]
+    end
+
     value_object "Switch" do
       attribute :value, Boolean
     end
@@ -134,19 +143,24 @@ Hecks.bluebook "Site" do
       transition "Fault"    => "faulted",   from: "requested"
     end
 
-    # `hecks site site_projection.project_site <project> [out=<dir>] [--check]`. With `check` nothing is written: a
-    # routes.ts that differs from the table is faulted, naming the file, so a CI job fails on drift.
+    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [extension=ts|mts] [--check]`.
+    # With `check` nothing is written: a routes.ts that differs from the table is faulted, naming the
+    # file, so a CI job fails on drift.
     command "ProjectSite" do
       goal "Project a site's route table into routes.ts, or with check only compare it with the file on disk"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :out,    Location, optional: true
-      attribute :check,  Switch,   optional: true
+      attribute :domain,    DomainPath
+      attribute :run,       RunKey
+      attribute :out,       Location,  optional: true
+      attribute :template,  Location,  optional: true
+      attribute :extension, Extension, optional: true
+      attribute :check,     Switch,    optional: true
 
       sets :domain
       sets :run
       sets :out
+      sets :template
+      sets :extension
       sets :check
 
       emits "SiteProjectionRequested"

data/lib/hecks/storehouse.rb

@@ -230,10 +230,44 @@ module Hecks
       result = runtime.dispatch_flat(spec[:command], envelope)
       ok(summary: summary,
          id:      result.id,
-         state:   result.state.nil? ? nil : Doors::JsonDoor.materialize(result.state),
+         state:   settled_state(runtime, spec, result),
          events:  result.events.map { |event| { name: event.name, payload: Doors::JsonDoor.materialize(event.payload) } })
     end
 
+    # The record as its repository holds it once every reaction has run, which is the state the
+    # dispatch resulted in; the handle's own state is the record as the command left it, so a run
+    # record that a reaction completes would otherwise read as `requested`. Falls back to the
+    # handle's state for a command that belongs to no top-level aggregate or whose record cannot be
+    # read.
+    # :nodoc:
+    def settled_state(runtime, spec, result)
+      return if result.state.nil?
+
+      bluebook = bluebook_for(runtime)
+      head = spec[:command].split("::", 2).last
+      aggregate = bluebook.aggregates.find { |candidate| candidate.hecks_name == head.split(".").first } if
+        head.count(".") == 1
+      record = aggregate && runtime.registry.repository(bluebook.name, aggregate)&.find(result.id)&.to_h
+      Doors::JsonDoor.materialize(record || result.state)
+    end
+
+    # What a caller needs to call each of the named commands: its qualified name, the role it
+    # declares, what it does, and its argument names, a trailing `*` marking a required one.
+    #
+    # @param runtime [Runtime::Dispatcher] the booted domain
+    # @param names [Array<String>] short or qualified command names
+    # @return [Array<String>] one line per name that resolves, in order
+    def command_guide(runtime, names)
+      cli = Projector.call(:cli, bluebook: bluebook_for(runtime), options: { program: "mcp" })
+      names.filter_map do |name|
+        spec = resolve!(cli, name.to_s, asking: false)
+        arguments = spec[:arguments].map { |arg| arg[:path].split(".").first + (arg[:required] ? "*" : "") }
+        "#{name} (role #{spec[:role] || 'none'}): #{spec[:summary]}. Arguments: #{arguments.uniq.join(', ')}"
+      rescue Runtime::NotFound
+        nil
+      end
+    end
+
     # :nodoc:
     def dry_run_outcome(runtime, spec, envelope, summary:)
       flat = flatten_legacy(envelope, spec[:receiver], spec[:legacy_receiver])

data/lib/hecks/tools/comment_style.rb

@@ -946,10 +946,12 @@ module Hecks
           $CHILD_STATUS.success? ? out : nil
         end
 
-        # `.rb` files, plus extensionless scripts with a Ruby shebang.
+        # `.rb` files, plus extensionless scripts with a Ruby shebang. The first line is read as
+        # bytes, so an extensionless binary (a compiled test fixture's output) is passed over
+        # rather than refused for not being UTF-8.
         def ruby_files(dir)
           scripts = Dir[File.join(dir, "**", "*")].select do |path|
-            File.file?(path) && File.extname(path).empty? && File.open(path, &:gets).to_s.match?(/\A#!.*ruby/)
+            File.file?(path) && File.extname(path).empty? && File.open(path, "rb", &:gets).to_s.match?(/\A#!.*ruby/n)
           end
           Dir[File.join(dir, "**", "*.rb")] + scripts
         end

data/lib/hecks/tools/rust_comment_style.rb

@@ -30,7 +30,7 @@ module Hecks
       DOC_LINE = %r{\A\s*(?:///(?!/)|//!)}
 
       # `// TMPL:name BEGIN`/`END` sentinels are parsed verbatim by
-      # `rust/project/exemplar.rb`; every prose rule skips them outright.
+      # `rust/codegen/src/exemplar.rs`; every prose rule skips them outright.
       TMPL_MARKER = /\bTMPL:\S+\s+(?:BEGIN|END)\b/i
       MOD_DOC_LINE = %r{\A\s*//!}
       ATTR_LINE = /\A\s*#\[/

data/lib/hecks/tools/site_routes.rb

@@ -14,41 +14,47 @@ module Hecks
     # it declares an edge, into the behaviours and listener rules of its template
     # (`Projections::Site::SiteCdn`).
     #
-    #   hecks site site_projection.project_site [<project>] [--out=<dir>] [--check]
+    #   hecks site site_projection.project_site [<project>] [--out=<dir>] [--template=<file>]
+    #                                           [--extension=ts|mts] [--check]
     #
-    # `<project>` is the directory whose `bluebook/` holds the chapter that declares the rows and a
-    # hecksagon that attaches Site; it defaults to the checkout. `routes.ts` is written to
-    # `<project>/generated` unless `--out` names another directory. The template is rewritten in
-    # place between its `BEGIN`/`END GENERATED site_cdn` markers, or under `--out` a copy of it is
-    # written at the same relative path. With `--check` nothing is written: the tool answers 1 and
-    # names each file that differs from the table.
+    # `<project>` (default: the working directory) holds `bluebook/` and the `vendor/` it attaches
+    # from. `routes.ts` goes to `<project>/generated` or to `--out`, anywhere. The template is the
+    # `Edge` row's, relative to the project, or `--template`, anywhere; it is rewritten in place
+    # between its `BEGIN`/`END GENERATED site_cdn` markers. With `--out` alone, `--out` receives a
+    # copy of it instead. `--extension=mts` names the module `routes.mts`; `--check` writes nothing.
     module SiteRoutes
       # Where the files go, relative to the project, when `--out` names no directory.
       DEFAULT_OUT = "generated"
 
-      USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] [--check]"
+      # The extensions the module may take; the first is the default.
+      EXTENSIONS = %w[ts mts].freeze
+
+      USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] " \
+              "[--template=<file>] [--extension=#{EXTENSIONS.join('|')}] [--check]".freeze
 
       module_function
 
       # Projects the route table, writes what differs and prints a line for each file written.
       #
       # @param argv [Array<String>] the project directory, then the flags
-      # @param root [String] the checkout, used as the project when `argv` names none
+      # @param root [String] the project used when `argv` names none; the working directory
       # @return [Integer] 0, or 1 when `--check` finds a file out of date
-      # @raise [SystemExit] with the reason on stderr when the project declares no route table or
-      #   the table is refused
-      def main(argv, root: Tools::ROOT)
+      # @raise [SystemExit] with the reason on stderr when the project declares no route table, the
+      #   table is refused, or a flag is refused
+      def main(argv, root: Dir.pwd)
         argv = argv.dup
-        out = nil
+        out = template = extension = nil
         check = false
         OptionParser.new do |parser|
           parser.on("--out=DIR") { |value| out = value }
+          parser.on("--template=FILE") { |value| template = value }
+          parser.on("--extension=EXT") { |value| extension = value }
           parser.on("--check") { check = true }
         end.parse!(argv)
         project = argv.empty? ? root : File.expand_path(argv.shift)
         abort USAGE unless argv.empty?
 
-        files = projection(project, out: out)
+        files = projection(project, out: out, template: template, extension: extension)
         stale = files.reject { |path, text| File.file?(path) && File.read(path) == text }.keys
         return report(stale, project, check) if check
 
@@ -63,16 +69,26 @@ module Hecks
 
       # @param root [String] the project directory
       # @param out [String, nil] the directory to write to; `generated/` of the project when nil
+      # @param template [String, nil] the template to rewrite in place, wherever it lies; the
+      #   `Edge` row's template, relative to the project, when nil
+      # @param extension [String, nil] `ts` (the default) or `mts`, the module's file extension
       # @return [Hash{String => String}] each file's absolute path to the text it should hold
-      # @raise [SystemExit] when the project declares no route table or the table is refused
-      def projection(root, out: nil)
+      # @raise [SystemExit] when the project declares no route table, the table is refused, or a
+      #   path or the extension is refused
+      def projection(root, out: nil, template: nil, extension: nil)
+        extension ||= EXTENSIONS.first
+        unless EXTENSIONS.include?(extension)
+          abort "project_site: --extension is one of #{EXTENSIONS.join(', ')}, not #{extension.inspect}"
+        end
+        dir = out ? File.expand_path(out) : File.join(root, DEFAULT_OUT)
+        abort "project_site: --out #{dir} is a file; it names the directory routes.#{extension} goes in" if File.file?(dir)
+
         registry = registry_for(root)
         chapter = Projections::Site::Table.chapter(registry)
         table = Projections::Site::Table.read(chapter, registry: registry)
         files = Projector.call(:site_routes_ts, bluebook: chapter, options: { table: table })
-        dir = out ? File.expand_path(out) : File.join(root, DEFAULT_OUT)
-        written = files.to_h { |name, text| [File.join(dir, name), text] }
-        written.merge(template_files(root, out, chapter, table, registry))
+        written = files.to_h { |name, text| [File.join(dir, name.sub(/\.ts\z/, ".#{extension}")), text] }
+        written.merge(template_files(root, out, chapter, table, registry, template: template))
       rescue Projections::Site::Table::Invalid => e
         abort "project_site: #{e.message}"
       end
@@ -84,25 +100,50 @@ module Hecks
       # @param chapter [Bluebook::Chapter] the chapter that declares the route table
       # @param table [Projections::Site::Table] the checked table
       # @param registry [Hecks::Runtime::Registry] the registry the project booted into
+      # @param template [String, nil] a template named on the command line, rewritten in place
       # @return [Hash{String => String}] the template's path to its text; empty with no edge
-      # @raise [SystemExit] when the template is missing or lacks a region
-      def template_files(root, out, chapter, table, registry)
-        edge = Projections::Site::Edge.read(chapter, table: table, vocabulary: Projections::Site::Table.vocabulary(registry))
-        return {} unless edge
+      # @raise [SystemExit] when a template is named and the project declares no edge, the
+      #   template is missing or lacks a region it needs, or holds a region an edge without a load
+      #   balancer does not use
+      def template_files(root, out, chapter, table, registry, template: nil)
+        edge = Projections::Site::Edge.read(chapter, table: table, template: template,
+                                                     vocabulary: Projections::Site::Table.vocabulary(registry))
+        unless edge
+          abort "project_site: --template names #{template}, but the project declares no Edge rows" if template
+          return {}
+        end
 
         regions = Projector.call(:site_cdn, bluebook: chapter, options: { table: table, edge: edge })
-        relative = edge.setting.template
-        source = File.join(root, relative)
-        abort "project_site: the template #{relative} does not exist in #{root}" unless File.file?(source)
+        relative = template || edge.setting.template
+        source = template ? File.expand_path(template) : File.join(root, relative)
+        unless File.file?(source)
+          abort "project_site: the template #{relative} does not exist#{" in #{root}" unless template}"
+        end
 
-        text = regions.reduce(File.read(source)) do |current, (name, block)|
+        text = rewritten(File.read(source), regions, relative, edge)
+        in_place = template || out.nil?
+        { (in_place ? source : File.join(File.expand_path(out), relative)) => text }
+      end
+
+      # @param text [String] the template
+      # @param regions [Hash{String => String}] each region's name to the block that goes in it
+      # @param relative [String] the template's name, for a message
+      # @param edge [Projections::Site::Edge] the checked edge
+      # @return [String] the template with each region rewritten
+      # @raise [SystemExit] when a region is missing, or a listener_rules region is left behind
+      #   by an edge with no load balancer
+      def rewritten(text, regions, relative, edge)
+        if !edge.alb? && Projections::Site::Regions.region?(text, "listener_rules")
+          abort "project_site: #{relative} has a BEGIN/END GENERATED site_cdn listener_rules region, " \
+                "and the Edge row says alb: false; remove the region"
+        end
+        regions.reduce(text) do |current, (name, block)|
           unless Projections::Site::Regions.region?(current, name)
             abort "project_site: #{relative} has no BEGIN/END GENERATED site_cdn #{name} region"
           end
 
           Projections::Site::Regions.replace(current, name, block)
         end
-        { (out ? File.join(File.expand_path(out), relative) : source) => text }
       end
 
       # Loads the project's chapters the way a deploy does: the bluebooks, then the hecksagons that

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.2.0".freeze
+  VERSION = "3.2.1".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -51,7 +51,7 @@ module Hecks
       ].freeze,
       "CiGate" => [
         {"name"=>"runtime_changed", "workflow"=>"ci.yml", "mode"=>"touches", "pattern"=>"^lib/hecks/runtime/", "push"=>"skip", "label"=>"does this change touch lib/hecks/runtime/**?"}.freeze,
-        {"name"=>"postgres_io_relevant_changed", "workflow"=>"ci-postgres-io-parallel.yml", "mode"=>"skips_unless", "pattern"=>"^(docs/|editors/|release/|deploy/|\\.claude/|\\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests|project)/|rust/project\\.rb$|rust/project_rust_pipeline\\.rb$|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"before_sha", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
+        {"name"=>"postgres_io_relevant_changed", "workflow"=>"ci-postgres-io-parallel.yml", "mode"=>"skips_unless", "pattern"=>"^(docs/|editors/|release/|deploy/|\\.claude/|\\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"before_sha", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
       ].freeze,
       "Comparison" => [
         {"symbol"=>">=", "compares_less_than"=>"true", "compares_equal"=>"false", "negated"=>"true"}.freeze,

data/lib/hecks.rb

@@ -34,6 +34,7 @@ require_relative "hecks/doors/cli_runner"
 require_relative "hecks/storehouse"
 require_relative "hecks/mcp_stdio_guard"
 require_relative "hecks/doors/mcp_door_scope"
+require_relative "hecks/doors/mcp_guide_cache"
 require_relative "hecks/framework"
 require_relative "hecks/vendoring"
 require_relative "hecks/embryonaut_bluebook"

data/rust/build/src/lineage_pass.rs

@@ -1,5 +1,5 @@
 //! Rust port of `Exporter.lineage` (`lib/hecks/projector/exporter.rb`), by way
-//! of `rust/project_rust_pipeline.rb::derive_lineage`.
+//! of the retired Ruby pipeline's `derive_lineage`.
 
 use std::collections::HashMap;
 use std::path::Path;

data/rust/build/src/pipeline.rs

@@ -1,4 +1,4 @@
-//! Rust port of `RustProjectPipeline.call` (`rust/project_rust_pipeline.rb`) —
+//! Rust port of the retired Ruby pipeline's `RustProjectPipeline.call` —
 //! this crate's own orchestration core.
 
 use std::path::{Path, PathBuf};

data/rust/codegen/src/attr.rs

@@ -1,5 +1,5 @@
 //! Free-function accessors over an `IR::Attribute#to_h`-shaped `Json::Object`, mirroring the
-//! bare Hash lookups in rust/project/*.rb.
+//! bare Hash lookups the retired Ruby generator used.
 
 use crate::json::Json;
 

data/rust/codegen/src/bridging.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/bridging.rb`: cross-type coercion checks for `:set` and `:append` RHS.
+//! Port of the retired Ruby generator's `bridging.rb`: cross-type coercion checks for `:set` and `:append` RHS.
 
 use crate::json::Json;
 use crate::literal::Literal;

data/rust/codegen/src/commands.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/commands.rb`: emits the per-command dispatch functions.
+//! Port of the retired Ruby generator's `commands.rb`: emits the per-command dispatch functions.
 
 use crate::exemplar::Exemplar;
 use crate::json::Json;

data/rust/codegen/src/constraints.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/constraints.rb`: `admits:` and `pattern:` check emission.
+//! Port of the retired Ruby generator's `constraints.rb`: `admits:` and `pattern:` check emission.
 
 use crate::exemplar::Exemplar;
 use crate::json::Json;

data/rust/codegen/src/dependency_planning.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/dependency_planning.rb`, an independent re-derivation of the
+//! Port of the retired Ruby generator's `dependency_planning.rb`, an independent re-derivation of the
 //! Analyzer's `complete_state? && state_independent?` predicate. Mirrors the Ruby file.
 
 use crate::json::Json;

data/rust/codegen/src/domain_generator.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/domain_generator.rb`'s `DomainGenerator.call`: the per-aggregate
+//! Port of the retired Ruby generator's `domain_generator.rb`'s `DomainGenerator.call`: the per-aggregate
 //! `.rs` files plus `registry.rs`. `metadata.rs` and `ir.json` are not emitted here.
 
 use crate::exemplar::Exemplar;
@@ -1181,7 +1181,7 @@ pub fn generate(
             None,
             None,
             Some(format!(
-                "read via rust/host's journal::read_lineage_head_all/_by_id, written via journal::append_lineage_mutation — both generic over storage_name (\"{}\"), dispatched OUTSIDE the WASM kernel/InMemoryRepository path entirely, matching Ruby's own CommandInterpreter routing for a Postgres-bound aggregate (rust/project.rb's own header)",
+                "read via rust/host's journal::read_lineage_head_all/_by_id, written via journal::append_lineage_mutation — both generic over storage_name (\"{}\"), dispatched OUTSIDE the WASM kernel/InMemoryRepository path entirely, matching Ruby's own CommandInterpreter routing for a Postgres-bound aggregate (rust/codegen/src/domain_generator.rs)",
                 lineage_aggregate.get("storage_name").map(Json::to_s).unwrap_or_default()
             )),
         );

data/rust/codegen/src/exemplar.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/exemplar.rb`: loads the template shapes in `rust/src/exemplar/*.rs`.
+//! Port of the retired Ruby generator's `exemplar.rb`: loads the template shapes in `rust/src/exemplar/*.rs`.
 //! Both codegens read those files at runtime, so the shapes cannot drift.
 use std::collections::HashMap;
 use std::path::PathBuf;

data/rust/codegen/src/expr_emitter.rs

@@ -1,4 +1,4 @@
-//! Port of `rust/project/expr_emitter.rb`: turns each IR rule's `ast` tree into `Expr` source.
+//! Port of the retired Ruby generator's `expr_emitter.rb`: turns each IR rule's `ast` tree into `Expr` source.
 //! A literal-array `include?` never reaches here; `AstJson` rewrites it to an or of equalities.
 
 use crate::json::Json;