hecks 3.5.0 → 3.7.0

data/lib/hecks/tools/translation_audit.rb

@@ -5,6 +5,9 @@ require "hecks"
 require "hecks/ports/persistence/plugins/era"
 require "json"
 require_relative "../tools"
+require_relative "translation_audit/domain_loading"
+require_relative "translation_audit/edges"
+require_relative "translation_audit/verdicts"
 
 module Hecks
   module Tools
@@ -13,6 +16,14 @@ module Hecks
     #
     #   hecks audit_translation <domain> [--approve]
     module TranslationAudit
+      # What one audit run works on: the loaded domain, its open journal, and whether `--approve`
+      # was given.
+      Session = Struct.new(:registry, :bluebook, :directory, :db, :lineage, :approve)
+
+      extend DomainLoading
+      extend Edges
+      extend Verdicts
+
       module_function
 
       # Audits the edge and prints each aggregate's verdict and samples.
@@ -28,179 +39,37 @@ module Hecks
 
         registry, bluebook, directory = load_domain(domain_path)
         db, lineage = open_lineage(registry, bluebook)
-        audit(registry, bluebook, directory, db, lineage, approve)
-      end
-
-      # @param domain_path [String] the domain directory
-      # @return [Array] the registry, its bluebook and the bluebook directory
-      def load_domain(domain_path)
-        loading = Hecks::Ports::Loading.bootstrap
-        directory = loading.bluebook_directory(domain_path)
-        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        begin
-          Hecks.with_registry(registry) do
-            loading.load_library
-            loading.load_project(loading.shared_root(nil, directory))
-            # Passes an environment overlay to `load_domain`, as `scaffold_translation` does.
-            loading.load_domain(directory, environment: ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
-          end
-        rescue Hecks::Bluebook::DSL::Malformed => e
-          abort "REFUSED at load: #{e.message}"
-        end
-        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
-        [registry, bluebook, directory]
+        audit(Session.new(registry, bluebook, directory, db, lineage, approve))
       end
 
-      # @param registry [Hecks::Runtime::Registry] the loaded registry
-      # @param bluebook [Object] the domain's bluebook
-      # @return [Array] the open connection and its ensured lineage
-      # @raise [SystemExit] when the bound adapter is not lineage-capable
-      def open_lineage(registry, bluebook)
-        first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
-        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
-        capable =
-          begin
-            adapter_class = registry.adapter_class(adapter_name)
-            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
-          rescue StandardError
-            false
-          end
-        unless capable
-          abort "the audit reads a lineage journal; #{bluebook.name} is bound to #{adapter_name}, " \
-                "not PostgresEra"
-        end
+      # @param session [Session] the loaded domain and its open journal
+      # @return [Integer] the exit status
+      def audit(session)
+        return hold_first_era(session) if session.lineage.eras.empty?
 
-        settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
-        # The same `HECKS_SCHEMA` support as `scaffold_translation`.
-        settings = settings.merge(schema: ENV["HECKS_SCHEMA"]) if ENV["HECKS_SCHEMA"]
-        db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
-        lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
-        lineage.ensure_base!
-        [db, lineage]
+        audit_edge(session, edge_chain(session.registry, session.bluebook, session.lineage))
       end
 
+      # @param found [Array, nil] the era ordinal and the chain of translations ending in it, or nil
+      #   when there is no edge
       # @return [Integer] the exit status
-      def audit(registry, bluebook, directory, db, lineage, approve)
-        if lineage.eras.empty?
-          lineage.hold_first!(Hecks::Runtime::EraCheck.source_text_for(bluebook, directory),
-                              projection: Hecks::Runtime::StorageShape.project(bluebook))
-          puts "#{bluebook.name} held era 1 just now — no edge to audit."
-          db.close
-          return 0
-        end
-
-        era, chain = edge_chain(registry, bluebook, lineage)
+      def audit_edge(session, found)
+        era, chain = found
         return 0 unless era
 
         edge = chain.last[:translation]
-        failed = report(bluebook, lineage, edge, era, chain)
-        conclude(db, lineage, edge, failed, approve)
-      end
-
-      # The era the edge leads to and the chain of translations ending in it, or nil when the
-      # journal stands at era 1 with nothing to audit.
-      #
-      # @return [Array, nil] the era ordinal and the chain
-      def edge_chain(registry, bluebook, lineage)
-        manager = Hecks::Adapters::PostgresEra::LineageManager
-        eras = lineage.eras
-        latest = eras.last
-        current_shape = Hecks::Runtime::StorageShape.project(bluebook)
-        held_shape = Hecks::Runtime::StorageShape.project(manager.shadow(latest[:held_text]))
-
-        if held_shape == current_shape
-          era = latest[:ordinal]
-          if era == 1
-            puts "#{bluebook.name} stands at era 1 — no edge to audit."
-            return nil
-          end
-          [era, manager.edge_chain(registry, bluebook, eras, latest[:label])]
-        else
-          # a pending edge: audit it before any mint
-          manager.ensure_named!(lineage, latest)
-          latest = lineage.eras.last
-          to_label = Hecks::Runtime::StorageShape.mint_hash(bluebook)[0, Hecks::Runtime::StorageShape::LABEL_LENGTH]
-          pending = registry.translations.find do |t|
-            t.domain == bluebook.name && t.from == latest[:label] && t.to == to_label
-          end
-          pending or abort "no translation edge leads #{latest[:label]} to #{to_label} — " \
-                           "run hecks scaffold_translation first"
-          chain = begin
-            manager.edge_chain(registry, bluebook, eras, latest[:label])
-          rescue StandardError
-            []
-          end
-          [latest[:ordinal] + 1, (chain || []) + [{ translation: pending }]]
-        end
+        failed = report(session.bluebook, session.lineage, edge, era, chain)
+        conclude(session.db, session.lineage, edge, failed, session.approve)
       end
 
-      # Prints each aggregate's verdict.
+      # A journal with no era yet holds the bluebook as its first, so there is no edge to audit.
       #
-      # @return [Boolean] whether any aggregate's audit was refused
-      def report(bluebook, lineage, edge, era, chain)
-        failed = false
-        bluebook.aggregates.each do |aggregate|
-          declared = edge.for_aggregate(aggregate.name)
-          after = begin
-            lineage.translated_latest(aggregate, era, chain)
-          rescue PG::Error => e
-            abort "REFUSED: #{e.message.strip}"
-          end
-          before = if chain.size > 1
-                     lineage.translated_latest(aggregate, era, chain[0..-2])
-                   else
-                     lineage.ancestor_latest(aggregate, era, chain)
-                   end
-          verdict = Hecks::Translation::Audit.check(aggregate: aggregate, declared: declared,
-                                                    before: before, after: after)
-          print_verdict(bluebook, aggregate, edge, after, verdict)
-          failed ||= !verdict.ok?
-        end
-        failed
-      end
-
-      # @return [void]
-      def print_verdict(bluebook, aggregate, edge, after, verdict)
-        puts "── #{bluebook.name}::#{aggregate.name} (edge #{edge.from} → #{edge.to}, " \
-             "#{after.size} record#{'s' unless after.size == 1})"
-        verdict.violations.each { |violation| puts "   REFUSED: #{violation}" }
-        puts "   dropped (declared data loss): #{verdict.dropped.join(', ')}" unless verdict.dropped.empty?
-        puts "   unfed (no rule, no default — add default: if required): #{verdict.unfed.join(', ')}" unless verdict.unfed.empty?
-        verdict.samples.each do |sample|
-          puts "   ##{sample[:id]}"
-          puts "     before: #{JSON.generate(sample[:before])}" if sample[:before]
-          puts "     after:  #{JSON.generate(sample[:after])}" if sample[:after]
-        end
-      end
-
-      # @return [Integer] the exit status
-      def conclude(db, lineage, edge, failed, approve)
-        if failed
-          db.close
-          puts "AUDIT REFUSED."
-          return 1
-        end
-
-        needs_approval = edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
-        if needs_approval && approve
-          # Binds to what was reviewed — this edge and the journal as it stands now — so it must
-          # live in the database, not the repo.
-          lineage.record_approval!(
-            from: edge.from, to: edge.to,
-            edge_digest: Hecks::Translation::Audit.edge_digest(edge)
-          )
-          db.close
-          puts "AUDIT PASSED — approval recorded in the database, bound to this edge and this journal."
-          puts "A journal that advances before the mint invalidates it; re-run with --approve if that happens."
-        elsif needs_approval
-          db.close
-          puts "AUDIT PASSED — this edge carries a compute or rekey rule, and the samples above are " \
-               "its ONLY verification."
-          puts "If they show what you intended, run again with --approve; the mint refuses until you do."
-        else
-          db.close
-          puts "AUDIT PASSED — review the samples above; intent is yours to approve."
-        end
+      # @return [Integer] the exit status, 0
+      def hold_first_era(session)
+        session.lineage.hold_first!(Hecks::Runtime::EraCheck.source_text_for(session.bluebook, session.directory),
+                                    projection: Hecks::Runtime::StorageShape.project(session.bluebook))
+        puts "#{session.bluebook.name} held era 1 just now — no edge to audit."
+        session.db.close
         0
       end
     end

data/lib/hecks/tools/translation_scaffold/reporting.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module TranslationScaffold
+      # Says what the written edge file leaves to decide.
+      module Reporting
+        # @return [void]
+        def report(path, diffed)
+          text = File.read(path)
+          unresolved = text.scan(/^\s*unresolved /).size
+          unclaimed = diffed ? diffed[:unclaimed] : []
+          puts "wrote #{path}"
+          unclaimed.each { |name| puts unclaimed_message(name) }
+          verdict = verdict_message(unresolved, unclaimed)
+          puts verdict if verdict
+        end
+
+        def unclaimed_message(name)
+          "UNCLAIMED: #{name} existed and now doesn't, and its successor is ambiguous — " \
+            "add `aggregate \"NewName\", was: #{name.inspect}` (with its rules) or " \
+            "`retired #{name.inspect}` by hand."
+        end
+
+        # @return [String, nil] what is left to decide, nil when unclaimed names say it all
+        def verdict_message(unresolved, unclaimed)
+          if unresolved.zero? && unclaimed.empty?
+            "0 unresolved — this shape change costs one extra boot and no typing. " \
+              "Check it with hecks audit_translation, then boot."
+          elsif unresolved.positive?
+            "#{unresolved} unresolved — decide what each became (rename/move/convert/drop, or " \
+              "compute on PostgresEra), then boot."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/translation_scaffold.rb

@@ -4,6 +4,7 @@ require "hecks"
 # The translation and scaffold machinery lives in the era persistence plugin (ADR 0033).
 require "hecks/ports/persistence/plugins/era"
 require_relative "../tools"
+require_relative "translation_scaffold/reporting"
 
 module Hecks
   module Tools
@@ -12,6 +13,8 @@ module Hecks
     #
     #   hecks scaffold_translation <domain>
     module TranslationScaffold
+      extend Reporting
+
       module_function
 
       # Writes the edge file and prints what is left to decide.
@@ -25,24 +28,29 @@ module Hecks
         domain_path = argv.shift or abort "usage: hecks scaffold_translation <domain>"
 
         registry, bluebook, directory = load_domain(domain_path)
+        scaffold(registry, bluebook, directory, bound_adapter(registry, bluebook))
+      end
+
+      # @return [String] the name of the adapter the domain is bound to
+      # @raise [SystemExit] when that adapter is not lineage-capable
+      def bound_adapter(registry, bluebook)
         first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
         adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
-        capable =
-          begin
-            adapter_class = registry.adapter_class(adapter_name)
-            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
-          rescue StandardError
-            false
-          end
         # Eras belong to the adapters that can carry data across them. An edge scaffolded for an
         # adapter that cannot apply it would be a document nothing will ever run.
-        unless capable
+        unless lineage_capable?(registry, adapter_name)
           abort "#{bluebook.name} is bound to #{adapter_name}, which holds no eras — " \
                 "a translation edge is only applied by a lineage-capable adapter. " \
                 "Bind PostgresEra, or change the shape and its stored data by hand."
         end
+        adapter_name
+      end
 
-        scaffold(registry, bluebook, directory, adapter_name)
+      def lineage_capable?(registry, adapter_name)
+        adapter_class = registry.adapter_class(adapter_name)
+        adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+      rescue StandardError
+        false
       end
 
       # @param domain_path [String] the domain directory
@@ -51,32 +59,56 @@ module Hecks
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)
         registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        Hecks.with_registry(registry) do
-          loading.load_library
-          loading.load_project(loading.shared_root(nil, directory))
-          # deliberately not translations/*.bluebook: an unresolved edge file refuses to load, and
-          # regenerating it is this tool's whole job
-          loading.load_each(directory, %w[*.port *.adapter])
-          loading.load_bluebooks(directory)
-          loading.load_each(directory, %w[*.hecksagon *.world])
-
-          # A domain that splits `persisted_by` per environment declares none in its base
-          # `.hecksagon`, so resolution fails without this overlay — opt-in via
-          # HECKS_PROJECT_ENVIRONMENT, a no-op otherwise.
-          if (target_environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
-            loading.load_each(directory, [File.join("environments", "#{target_environment}.hecksagon")])
-            loading.load_each(directory, [File.join("environments", "#{target_environment}.world")])
-          end
-        end
+        Hecks.with_registry(registry) { load_chapters(loading, directory) }
         bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
         [registry, bluebook, directory]
       end
 
+      # Loads the library, the project and the domain's files into the registry in scope.
+      def load_chapters(loading, directory)
+        loading.load_library
+        loading.load_project(loading.shared_root(nil, directory))
+        # deliberately not translations/*.bluebook: an unresolved edge file refuses to load, and
+        # regenerating it is this tool's whole job
+        loading.load_each(directory, %w[*.port *.adapter])
+        loading.load_bluebooks(directory)
+        loading.load_each(directory, %w[*.hecksagon *.world])
+        load_environment_overlay(loading, directory)
+      end
+
+      # A domain that splits `persisted_by` per environment declares none in its base
+      # `.hecksagon`, so resolution fails without this overlay — opt-in via
+      # HECKS_PROJECT_ENVIRONMENT, a no-op otherwise.
+      def load_environment_overlay(loading, directory)
+        target_environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil) or return
+
+        loading.load_each(directory, [File.join("environments", "#{target_environment}.hecksagon")])
+        loading.load_each(directory, [File.join("environments", "#{target_environment}.world")])
+      end
+
       # @return [Integer] 0
       def scaffold(registry, bluebook, directory, adapter_name)
         current_shape = Hecks::Runtime::StorageShape.project(bluebook)
-        manager = Hecks::Adapters::PostgresEra::LineageManager
+        db, lineage = open_lineage(registry, bluebook, adapter_name)
+        return hold_first_era(lineage, bluebook, directory, current_shape) if lineage.eras.empty?
+
+        latest, held_bluebook = held_era(lineage)
+        return matches_era(bluebook, latest) if Hecks::Runtime::StorageShape.project(held_bluebook) == current_shape
+
+        path = lineage_manager.scaffold!(registry, bluebook, lineage, latest, directory)
+        diffed = Hecks::Translation::Scaffold.diff(held_bluebook, bluebook)
+        db.close
+
+        report(path, diffed)
+        0
+      end
+
+      def lineage_manager
+        Hecks::Adapters::PostgresEra::LineageManager
+      end
 
+      # @return [Array] the open connection and its ensured lineage
+      def open_lineage(registry, bluebook, adapter_name)
         # `World#for_binding` keys settings by the world-declared adapter name (e.g.
         # "PostgresEra"); a bypassed name like "Postgres" finds nothing.
         settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
@@ -87,44 +119,29 @@ module Hecks
         db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
         lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
         lineage.ensure_base!
-        if lineage.eras.empty?
-          lineage.hold_first!(Hecks::Runtime::EraCheck.source_text_for(bluebook, directory),
-                              projection: current_shape)
-          puts "#{bluebook.name} held era 1 just now — nothing to scaffold."
-          return 0
-        end
+        [db, lineage]
+      end
+
+      # @return [Array] the journal's latest era and the bluebook it held
+      def held_era(lineage)
         latest = lineage.eras.last
-        held_bluebook = manager.shadow(latest[:held_text])
-        if Hecks::Runtime::StorageShape.project(held_bluebook) == current_shape
-          puts "#{bluebook.name} matches era #{latest[:ordinal]} — nothing to scaffold."
-          return 0
-        end
-        path = manager.scaffold!(registry, bluebook, lineage, latest, directory)
-        diffed = Hecks::Translation::Scaffold.diff(held_bluebook, bluebook)
-        db.close
+        [latest, lineage_manager.shadow(latest[:held_text])]
+      end
 
-        report(path, diffed)
+      # A journal with no era yet holds the bluebook as its first, so there is nothing to scaffold.
+      #
+      # @return [Integer] 0
+      def hold_first_era(lineage, bluebook, directory, current_shape)
+        lineage.hold_first!(Hecks::Runtime::EraCheck.source_text_for(bluebook, directory),
+                            projection: current_shape)
+        puts "#{bluebook.name} held era 1 just now — nothing to scaffold."
         0
       end
 
-      # @return [void]
-      def report(path, diffed)
-        text = File.read(path)
-        unresolved = text.scan(/^\s*unresolved /).size
-        unclaimed = diffed ? diffed[:unclaimed] : []
-        puts "wrote #{path}"
-        unclaimed.each do |name|
-          puts "UNCLAIMED: #{name} existed and now doesn't, and its successor is ambiguous — " \
-               "add `aggregate \"NewName\", was: #{name.inspect}` (with its rules) or " \
-               "`retired #{name.inspect}` by hand."
-        end
-        if unresolved.zero? && unclaimed.empty?
-          puts "0 unresolved — this shape change costs one extra boot and no typing. " \
-               "Check it with hecks audit_translation, then boot."
-        elsif unresolved.positive?
-          puts "#{unresolved} unresolved — decide what each became (rename/move/convert/drop, or " \
-               "compute on PostgresEra), then boot."
-        end
+      # @return [Integer] 0
+      def matches_era(bluebook, latest)
+        puts "#{bluebook.name} matches era #{latest[:ordinal]} — nothing to scaffold."
+        0
       end
     end
   end

data/lib/hecks/tools.rb

@@ -23,6 +23,7 @@ module Hecks
       "argument_gate_matrix"           => ["tools/argument_gate_matrix", "ArgumentGateMatrix"],
       "project_ci_gates"               => ["tools/ci_gates", "CiGates"],
       "decide_ci_gate"                 => ["tools/ci_gate_decision", "CiGateDecision"],
+      "project_lanes"                  => ["tools/lanes", "Lanes"],
       "project_tools_doc"              => ["tools/tools_doc", "ToolsDoc"],
       "project_deploy"                 => ["tools/deploy_recipe", "DeployRecipe"],
       "project_site"                   => ["tools/site_routes", "SiteRoutes"],
@@ -38,6 +39,7 @@ module Hecks
       "heki_compact"                   => ["tools/heki_compaction", "HekiCompaction"],
       "fuzz"                           => ["tools/fuzz_sweep", "FuzzSweep"],
       "generate"                       => ["tools/sequence_script", "SequenceScript"],
+      "mutate"                         => ["tools/mutation_run", "MutationRun"],
       "corpus"                         => ["tools/corpus_report", "CorpusReport"],
       "evolve"                         => ["tools/evolve_run", "EvolveRun"],
       "query_ir"                       => ["tools/query_ir_run", "QueryIrRun"],

data/lib/hecks/vendoring.rb

@@ -30,25 +30,51 @@ module Hecks
     # @param ref [String] the commit-ish to export
     # @param subtree [String] repository-relative directory to export
     # @param into [String] the directory to replace with the export
-    # @param glob [String] pattern each exported file's name must match
-    # @param marker [String] name of the file recording the commit
+    # @param options [Hash] `glob:`, the pattern each exported file's name must match (`"*"`),
+    #   and `marker:`, the name of the file recording the commit (`MARKER`)
     # @return [Pin] the commit and where the files landed
     # @raise [Vendoring::Error] if the source or a matching file is missing
-    def self.pin(from:, ref:, subtree:, into:, glob: "*", marker: MARKER)
+    # @raise [ArgumentError] for any other keyword
+    def self.pin(from:, ref:, subtree:, into:, **options, &)
+      unknown = options.keys - %i[glob marker]
+      raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+      request = request_for(from, ref, subtree, into, options)
+      Dir.mktmpdir("hecks-vendoring") do |stage|
+        request.source.export(request.commit, request.files, stage)
+        pinned(stage, request, &)
+      end
+    end
+
+    # What one pin exports, and where it goes.
+    Request = Struct.new(:source, :commit, :files, :subtree, :into, :marker) do
+      # @return [String] the directory the exported subtree lands in
+      def pin_dir = File.join(into, File.basename(subtree))
+
+      # @return [Array<String>] the exported files' names
+      def names = files.map { |file| File.basename(file) }
+    end
+
+    # @return [Request] the commit and files to export
+    # @raise [Vendoring::Error] if the source or a matching file is missing
+    def self.request_for(from, ref, subtree, into, options)
       source = GitSource.new(from)
       commit = source.commit(ref)
+      glob = options.fetch(:glob, "*")
       files = source.files(commit, subtree, glob)
       raise Error, "no #{glob} files in #{subtree} at #{ref} in #{source.path}" if files.empty?
 
-      Dir.mktmpdir("hecks-vendoring") do |stage|
-        source.export(commit, files, stage)
-        staged = File.join(stage, subtree)
-        extras = block_given? ? yield(staged, commit) : nil
-        install(staged, into, marker, commit, extras || {})
-        Pin.new(commit: commit, dir: File.join(into, File.basename(subtree)),
-                files: files.map { |file| File.basename(file) })
-      end
+      Request.new(source, commit, files, subtree, into, options.fetch(:marker, MARKER))
+    end
+
+    # Runs the optional hook on the staged export, installs what it leaves, and describes it.
+    def self.pinned(stage, request)
+      staged = File.join(stage, request.subtree)
+      extras = block_given? ? yield(staged, request.commit) : nil
+      install(staged, request.into, request.marker, request.commit, extras || {})
+      Pin.new(commit: request.commit, dir: request.pin_dir, files: request.names)
     end
+    private_class_method :request_for, :pinned
 
     # Replaces `into` with the staged files, the marker and any extras.
     def self.install(staged, into, marker, commit, extras)

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.5.0".freeze
+  VERSION = "3.7.0".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -50,7 +50,7 @@ module Hecks
         {"name"=>"workspace"}.freeze
       ].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"=>"runtime_changed", "workflow"=>"ci.yml", "mode"=>"touches", "pattern"=>"^lib/hecks/runtime/", "push"=>"before_sha", "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)/|\\.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" => [
@@ -106,6 +106,10 @@ module Hecks
         {"type"=>"Array", "strategy"=>"membership"}.freeze,
         {"type"=>"String", "strategy"=>"substring"}.freeze
       ].freeze,
+      "Lane" => [
+        {"name"=>"main", "guarded"=>"no", "pushers"=>"anyone", "feeds"=>"", "follows"=>"", "alert_after"=>""}.freeze,
+        {"name"=>"stable", "guarded"=>"yes", "pushers"=>"green", "feeds"=>"edge", "follows"=>"main", "alert_after"=>"4"}.freeze
+      ].freeze,
       "LoadOrder" => [
         {"glob"=>"*.port"}.freeze,
         {"glob"=>"*.adapter"}.freeze,
@@ -149,6 +153,7 @@ module Hecks
         {"name"=>"guided_generation", "type"=>"Boolean", "meaning"=>"Coverage-guided generation across one sweep's seeds (`Hecks::Fuzzing::CoverageCampaign`)."}.freeze,
         {"name"=>"corpus_splice_probability", "type"=>"Numeric", "meaning"=>"Fraction (0.0..1.0) of seeds that start from a prefix of an earlier seed's new coverage. Off by default: measured, it trades breadth for depth (banking reached 1.41x the deep-state tuples, chess lost 0.12x of all tuples), while favoring rare verbs alone never lost."}.freeze,
         {"name"=>"favor_rare_verbs", "type"=>"Integer", "meaning"=>"How many of the least-hit verbs the next seed weights up; 0 turns the lever off."}.freeze,
+        {"name"=>"runtime_coverage_feedback", "type"=>"Boolean", "meaning"=>"Whether guided generation also admits a seed to the corpus for reaching a new line or branch of the Ruby runtime (`Hecks::Fuzzing::RuntimeCoverage`), not only a new (verb, kind, state, mutation, outcome) tuple. Off by default: tracing every line slows each seed."}.freeze,
         {"name"=>"self_consistency_checks", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control query sweep.run` also runs the self-consistency pass (cold rehydration, replay idempotency, value-object JSON round trip) on the same generated sequence."}.freeze,
         {"name"=>"shrink_budget", "type"=>"Integer", "meaning"=>"Candidate replays `hecks quality_control query sweep.run` may spend shrinking one surprised check; 0 turns shrinking off. `concurrency` is never shrunk: a race does not reproduce on demand."}.freeze,
         {"name"=>"yield_weight_seconds", "type"=>"Integer", "meaning"=>"Seconds of staleness that one point of yield score is worth in `RotationPriority.pick`. Zero would make yield invisible, so pick a number that lets it matter."}.freeze,
@@ -358,6 +363,17 @@ module Hecks
         {"refusal"=>"AttributeAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it in a translation (backfill :{field}, default: ...), or declare it optional: true"}.freeze,
         {"refusal"=>"ProjectionAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"}.freeze
       ].freeze,
+      "RequiredCheck" => [
+        {"name"=>"rspec"}.freeze,
+        {"name"=>"checks"}.freeze,
+        {"name"=>"rspec_postgres_io"}.freeze,
+        {"name"=>"rspec_postgres_io_parallel"}.freeze,
+        {"name"=>"rspec_rust_io"}.freeze,
+        {"name"=>"rspec_rust_parser"}.freeze,
+        {"name"=>"rspec_rust_codegen"}.freeze,
+        {"name"=>"rspec_rust_host"}.freeze,
+        {"name"=>"rspec_fuzzing"}.freeze
+      ].freeze,
       "RetiredScript" => [
         {"script"=>"ir", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"ir"}.freeze,
         {"script"=>"shape", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"shape"}.freeze,
@@ -399,6 +415,7 @@ module Hecks
         {"script"=>"fuzz", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"fuzz"}.freeze,
         {"script"=>"generate", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"generate_sequence"}.freeze,
         {"script"=>"bench", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"bench"}.freeze,
+        {"script"=>"(new)", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"mutate"}.freeze,
         {"script"=>"(new)", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"hold_first"}.freeze,
         {"script"=>"project_deploy", "section"=>"Deploy", "aggregate"=>"Recipe", "verb"=>"project"}.freeze,
         {"script"=>"lint_deploy_recipes", "section"=>"Deploy", "aggregate"=>"MakefileCheck", "verb"=>"lint"}.freeze,

data/lib/rubocop/cop/hecks/fallback_hash_lookup.rb

@@ -42,15 +42,13 @@ module RuboCop
           # (`a[k] || b[k]`) fails this check and is correctly left alone.
           return unless lhs_receiver == rhs_receiver
 
-          add_offense(
-            node,
-            message: format(
-              MSG,
-              receiver: lhs_receiver.source,
-              lhs_key:  lhs_key.source,
-              rhs_key:  rhs_key.source
-            )
-          )
+          add_offense(node, message: offense_message(lhs_receiver, lhs_key, rhs_key))
+        end
+
+        private
+
+        def offense_message(receiver, lhs_key, rhs_key)
+          format(MSG, receiver: receiver.source, lhs_key: lhs_key.source, rhs_key: rhs_key.source)
         end
       end
     end

data/lib/rubocop/cop/hecks/thread_shared_ivar_mutation.rb

@@ -49,12 +49,7 @@ module RuboCop
           receiver = node.receiver
           return unless receiver
 
-          # `@ivar << x` has the ivar as receiver; `@ivar[k] = v` has it one `send` deeper.
-          ivar_node = if receiver.ivar_type?
-                        receiver
-                      elsif receiver.send_type? && receiver.receiver&.ivar_type?
-                        receiver.receiver
-                      end
+          ivar_node = ivar_node_of(receiver)
           return unless ivar_node
 
           check(node, ivar_node.children.first)
@@ -62,6 +57,13 @@ module RuboCop
 
         private
 
+        # `@ivar << x` has the ivar as receiver; `@ivar[k] = v` has it one `send` deeper.
+        def ivar_node_of(receiver)
+          return receiver if receiver.ivar_type?
+
+          receiver.receiver if receiver.send_type? && receiver.receiver&.ivar_type?
+        end
+
         def check(node, ivar_name)
           return unless inside_thread_shared_class?(node)
           return if inside_initialize?(node)