hecks 3.5.0 → 3.6.0

data/lib/hecks/hecks/adapters/journal_store/readings.rb

@@ -5,6 +5,8 @@ require "digest"
 require_relative "held_domain"
 require_relative "edge_audit"
 require_relative "compaction"
+require_relative "readings/scaffolding"
+require_relative "readings/attestation"
 
 module Hecks
   module Adapters
@@ -16,6 +18,9 @@ module Hecks
       # a domain that holds no era answers that it holds none, and only `hold_first` holds one.
       # What a reading refuses is a `Runtime::NotFound`, the refusal a launcher words as an answer.
       module Readings
+        include Scaffolding
+        include Attestation
+
         # Words the answer for a domain that holds no era.
         #
         # @param name [String] the domain's name
@@ -99,41 +104,6 @@ module Hecks
           raise Runtime::NotFound, held.incapable_reason unless held.capable?
         end
 
-        def scaffold(held, lineage, path)
-          eras = held.held_eras(lineage)
-          return Readings.no_era(held.bluebook.name, path) if eras.empty?
-
-          latest = held.named(eras.last)
-          shadow = PostgresEra::LineageManager.shadow(latest[:held_text])
-          if Runtime::StorageShape.project(shadow) == held.shape
-            return "#{held.bluebook.name} matches era #{latest[:ordinal]} — nothing to scaffold."
-          end
-
-          edge_text(held, latest, Translation::Scaffold.diff(shadow, held.bluebook))
-        end
-
-        def edge_text(held, latest, diffed)
-          label = Runtime::StorageShape.mint_hash(held.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
-          edge = Translation::Scaffold::Edge.new(
-            domain: held.bluebook.name, from: latest[:label], to: label, ordinal: latest[:ordinal] + 1,
-            label: label, aggregates: diffed[:aggregates], retired: diffed[:retired]
-          )
-          text = Translation::Scaffold.render(edge)
-          [*scaffold_notes(edge, text, diffed[:unclaimed]), text].join("\n")
-        end
-
-        def scaffold_notes(edge, text, unclaimed)
-          unresolved = text.scan(/^\s*unresolved /).size
-          notes = ["# Save as translations/#{edge.ordinal}-#{edge.label}.bluebook."]
-          notes << "# #{unresolved} unresolved: decide what each became, then boot." if unresolved.positive?
-          unclaimed.each do |name|
-            notes << "# 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}`."
-          end
-          notes << "# 0 unresolved: this shape change costs one extra boot and no typing." if notes.size == 1
-          notes
-        end
-
         def audit(held, lineage, path)
           eras = held.held_eras(lineage)
           return Readings.no_era(held.bluebook.name, path) if eras.empty?
@@ -154,33 +124,6 @@ module Hecks
             "AUDIT PASSED — review the samples above; intent is yours to approve."
           end
         end
-
-        def attest(held, lineage, ordinal)
-          era = raw_era(held, lineage, ordinal)
-          computed = Digest::SHA256.hexdigest(era[:held_text])
-          name = "#{held.bluebook.name} era #{ordinal}"
-          return "#{name}: the held text matches its digest — nothing to re-attest." if era[:held_digest] == computed
-
-          [
-            "#{name}: the held text does NOT match its recorded digest.",
-            "  recorded: #{era[:held_digest] || '(none)'}", "  computed: #{computed}", shape_line(held, era, ordinal),
-            "The held text AS IT NOW STANDS — the original is gone; this is what you would be attesting to:",
-            "─" * 72, era[:held_text], "─" * 72,
-            "Read it, then `hecks reattest #{held.bluebook.name} era=#{ordinal} --confirm` accepts it."
-          ].join("\n")
-        end
-
-        def shape_line(held, era, ordinal)
-          verdict = Translation::Reattest.shape_guard!(
-            domain: held.bluebook.name, ordinal: ordinal, text: era[:held_text], stored_hash: era[:hash],
-            stored_projection: era[:held_projection] && JSON.parse(era[:held_projection])
-          )
-          if verdict == :cosmetic
-            "  shape:    unchanged — the edit is cosmetic (the text still projects to era #{ordinal}'s minted name)"
-          else
-            "  shape:    era #{ordinal} was never named, so no shape comparison is possible — read carefully"
-          end
-        end
       end
     end
   end

data/lib/hecks/hecks/adapters/local_files.rb

@@ -49,17 +49,12 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `output:` the report that was printed
       # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file exists
       def scaffold(**held)
-        name   = plain(held[:name])
-        files  = stub_files(name, plain(held[:adapter]))
-        target = File.expand_path(plain(held[:dir]) || CLI::DomainStub.directory(name), Dir.pwd)
+        files  = stub_files(plain(held[:name]), plain(held[:adapter]))
+        target = stub_target(held)
         refuse_existing!(target, files.keys)
-        warn "warning: #{target} is inside the hecks clone; keep a service you deploy outside it." if inside_clone?(target)
+        warn_inside_clone(target)
 
-        files.each do |path, text|
-          full = File.join(target, path)
-          FileUtils.mkdir_p(File.dirname(full))
-          File.write(full, text)
-        end
+        write_files(target, files)
         report = scaffold_report(target, files.keys, plain(held[:adapter]))
         puts report
         { output: { value: report } }
@@ -67,6 +62,28 @@ module Hecks
 
       private
 
+      # The directory the stub is written into: the named one, or the snake-cased name under the
+      # current directory.
+      def stub_target(held)
+        File.expand_path(plain(held[:dir]) || CLI::DomainStub.directory(plain(held[:name])), Dir.pwd)
+      end
+
+      # Warns that a service written inside the hecks clone is not one to deploy from there.
+      def warn_inside_clone(target)
+        return unless inside_clone?(target)
+
+        warn "warning: #{target} is inside the hecks clone; keep a service you deploy outside it."
+      end
+
+      # Writes each stub file under `target`, creating the directories on the way.
+      def write_files(target, files)
+        files.each do |path, text|
+          full = File.join(target, path)
+          FileUtils.mkdir_p(File.dirname(full))
+          File.write(full, text)
+        end
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
 
       def stub_files(name, adapter)
@@ -81,7 +98,7 @@ module Hecks
         return if taken.empty?
 
         raise ConsoleCapture::Failure,
-              "nothing written; already there: #{taken.map { |full| shown(full) }.join(', ')}"
+              "nothing written; already there: #{taken.map { |full| shown(full) }.join(", ")}"
       end
 
       def inside_clone?(target)

data/lib/hecks/hecks/adapters/pg_admin/ownership.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class PgAdmin
+      # Makes the ledger role the owner of a database, its schema and everything in it, and says
+      # what was done and what already held.
+      module Ownership
+        # The relations in `public` the role does not own yet.
+        RELATIONS_SQL = <<~SQL
+          SELECT c.relname, c.relkind, pg_get_userbyid(c.relowner) AS owner
+          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p', 'S', 'v', 'm') AND pg_get_userbyid(c.relowner) <> $1
+          ORDER BY c.relkind, c.relname
+        SQL
+
+        # The functions in `public` the role does not own yet.
+        FUNCTIONS_SQL = <<~SQL
+          SELECT p.proname, pg_get_function_identity_arguments(p.oid) AS args
+          FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+          WHERE n.nspname = 'public' AND pg_get_userbyid(p.proowner) <> $1
+          ORDER BY p.proname
+        SQL
+
+        private
+
+        def ensure_role(admin, role, done, skipped)
+          found = admin.exec_params("SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = $1", [role])
+          return create_role(admin, role, done) if found.ntuples.zero?
+
+          refuse_privileged_role!(role, found[0]) if found[0]["rolsuper"] == "t" || found[0]["rolbypassrls"] == "t"
+          skipped << "role #{role} exists, ordinary"
+        end
+
+        def create_role(admin, role, done)
+          # CREATE ROLE has no IF NOT EXISTS, and concurrent creates can lose on the catalog
+          # index (unique_violation) as well as on duplicate_object, so the block rescues both.
+          admin.exec(<<~SQL)
+            DO $$ BEGIN
+              CREATE ROLE #{admin.quote_ident(role)} LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE;
+            EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
+            END $$
+          SQL
+          done << "created role #{role} (LOGIN, no SUPERUSER, no BYPASSRLS)"
+        end
+
+        def refuse_privileged_role!(role, found)
+          kind = found["rolsuper"] == "t" ? "a superuser" : "a BYPASSRLS role"
+          raise ConsoleCapture::Failure,
+                "role #{role} already exists as #{kind}: the era write-fence cannot bind it. " \
+                "Pick another role, or ALTER ROLE #{role} NOSUPERUSER NOBYPASSRLS first."
+        end
+
+        def hand_over_database(admin, database, role, done, skipped)
+          owner = admin.exec_params(
+            "SELECT pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = $1", [database]
+          )
+          refuse_missing_database!(database) if owner.ntuples.zero?
+          if owner[0]["owner"] == role
+            skipped << "database #{database} already owned by #{role}"
+          else
+            admin.exec("ALTER DATABASE #{admin.quote_ident(database)} OWNER TO #{admin.quote_ident(role)}")
+            done << "database #{database}: owner #{owner[0]["owner"]} -> #{role}"
+          end
+        end
+
+        def refuse_missing_database!(database)
+          raise ConsoleCapture::Failure,
+                "no database #{database}: createdb it first (PostgresEra provisions every table it " \
+                "needs on first connect, never the database itself)"
+        end
+
+        def hand_over_contents(db, role, done)
+          hand_over_schema(db, role, done)
+          hand_over_relations(db, role, done)
+          hand_over_functions(db, role, done)
+        end
+
+        def hand_over_schema(db, role, done)
+          schema = db.exec("SELECT pg_get_userbyid(nspowner) AS owner FROM pg_namespace WHERE nspname = 'public'")
+          return unless schema.ntuples.positive? && schema[0]["owner"] != role
+
+          db.exec("ALTER SCHEMA public OWNER TO #{db.quote_ident(role)}")
+          done << "schema public: owner #{schema[0]["owner"]} -> #{role}"
+        end
+
+        def hand_over_relations(db, role, done)
+          quoted = db.quote_ident(role)
+          relations = db.exec_params(RELATIONS_SQL, [role])
+          relations.each do |row|
+            db.exec("ALTER #{KINDS.fetch(row["relkind"])} #{db.quote_ident(row["relname"])} OWNER TO #{quoted}")
+          end
+          done << "#{relations.ntuples} relation(s) in public -> #{role}" if relations.ntuples.positive?
+        end
+
+        def hand_over_functions(db, role, done)
+          quoted = db.quote_ident(role)
+          functions = db.exec_params(FUNCTIONS_SQL, [role])
+          functions.each do |row|
+            db.exec("ALTER FUNCTION #{db.quote_ident(row["proname"])}(#{row["args"]}) OWNER TO #{quoted}")
+          end
+          done << "#{functions.ntuples} function(s) in public -> #{role}" if functions.ntuples.positive?
+        end
+
+        def ledger_report(database, role, done, skipped)
+          lines = ["#{database} is #{role}'s"]
+          done.each { |line| lines << "  did:     #{line}" }
+          skipped.each { |line| lines << "  already: #{line}" }
+          lines << "  bind it: database \"postgres://#{role}@localhost/#{database}\"" if done.any?
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/pg_admin.rb

@@ -2,6 +2,7 @@
 
 require "uri"
 require_relative "console_capture"
+require_relative "pg_admin/ownership"
 
 module Hecks
   module Adapters
@@ -13,6 +14,8 @@ module Hecks
     # creates the ledger database itself: PostgresEra provisions the tables it needs on first
     # connect, and an operator makes the database with `createdb`.
     class PgAdmin
+      include Ownership
+
       # The role the QA ledger connects as when none is named.
       DEFAULT_ROLE = "hecks_qa"
 
@@ -99,20 +102,21 @@ module Hecks
       def drop_database(**held)
         database = named(held)
         refuse_to_drop!(database)
-        with(dbname: "postgres") do |admin|
-          if exists?(admin, database)
-            admin.exec_params("SELECT pg_terminate_backend(pid) FROM pg_stat_activity " \
-                              "WHERE datname = $1 AND pid <> pg_backend_pid()", [database])
-            admin.exec("DROP DATABASE #{admin.quote_ident(database)}")
-            { report: { value: "dropped database #{database}" } }
-          else
-            { report: { value: "no database #{database}" } }
-          end
-        end
+        with(dbname: "postgres") { |admin| drop_if_exists(admin, database) }
       end
 
       private
 
+      # Ends the sessions on the database and drops it, or reports that it is not there.
+      def drop_if_exists(admin, database)
+        return { report: { value: "no database #{database}" } } unless exists?(admin, database)
+
+        admin.exec_params("SELECT pg_terminate_backend(pid) FROM pg_stat_activity " \
+                          "WHERE datname = $1 AND pid <> pg_backend_pid()", [database])
+        admin.exec("DROP DATABASE #{admin.quote_ident(database)}")
+        { report: { value: "dropped database #{database}" } }
+      end
+
       def refuse_to_drop!(database)
         if SYSTEM_DATABASES.include?(database.downcase) || configured_databases.include?(database)
           raise ConsoleCapture::Failure, "refusing to drop #{database}: it is the ledger, production or " \
@@ -140,83 +144,6 @@ module Hecks
         database
       end
 
-      def ensure_role(admin, role, done, skipped)
-        found = admin.exec_params("SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = $1", [role])
-        if found.ntuples.zero?
-          # CREATE ROLE has no IF NOT EXISTS, and concurrent creates can lose on the catalog
-          # index (unique_violation) as well as on duplicate_object, so the block rescues both.
-          admin.exec(<<~SQL)
-            DO $$ BEGIN
-              CREATE ROLE #{admin.quote_ident(role)} LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE;
-            EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
-            END $$
-          SQL
-          done << "created role #{role} (LOGIN, no SUPERUSER, no BYPASSRLS)"
-        elsif found[0]["rolsuper"] == "t" || found[0]["rolbypassrls"] == "t"
-          kind = found[0]["rolsuper"] == "t" ? "a superuser" : "a BYPASSRLS role"
-          raise ConsoleCapture::Failure,
-                "role #{role} already exists as #{kind}: the era write-fence cannot bind it. " \
-                "Pick another role, or ALTER ROLE #{role} NOSUPERUSER NOBYPASSRLS first."
-        else
-          skipped << "role #{role} exists, ordinary"
-        end
-      end
-
-      def hand_over_database(admin, database, role, done, skipped)
-        owner = admin.exec_params(
-          "SELECT pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = $1", [database]
-        )
-        if owner.ntuples.zero?
-          raise ConsoleCapture::Failure,
-                "no database #{database}: createdb it first (PostgresEra provisions every table it " \
-                "needs on first connect, never the database itself)"
-        elsif owner[0]["owner"] == role
-          skipped << "database #{database} already owned by #{role}"
-        else
-          admin.exec("ALTER DATABASE #{admin.quote_ident(database)} OWNER TO #{admin.quote_ident(role)}")
-          done << "database #{database}: owner #{owner[0]['owner']} -> #{role}"
-        end
-      end
-
-      def hand_over_contents(db, role, done)
-        quoted = db.quote_ident(role)
-        schema = db.exec("SELECT pg_get_userbyid(nspowner) AS owner FROM pg_namespace WHERE nspname = 'public'")
-        if schema.ntuples.positive? && schema[0]["owner"] != role
-          db.exec("ALTER SCHEMA public OWNER TO #{quoted}")
-          done << "schema public: owner #{schema[0]['owner']} -> #{role}"
-        end
-
-        relations = db.exec_params(<<~SQL, [role])
-          SELECT c.relname, c.relkind, pg_get_userbyid(c.relowner) AS owner
-          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
-          WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p', 'S', 'v', 'm') AND pg_get_userbyid(c.relowner) <> $1
-          ORDER BY c.relkind, c.relname
-        SQL
-        relations.each do |row|
-          db.exec("ALTER #{KINDS.fetch(row['relkind'])} #{db.quote_ident(row['relname'])} OWNER TO #{quoted}")
-        end
-        done << "#{relations.ntuples} relation(s) in public -> #{role}" if relations.ntuples.positive?
-
-        functions = db.exec_params(<<~SQL, [role])
-          SELECT p.proname, pg_get_function_identity_arguments(p.oid) AS args
-          FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
-          WHERE n.nspname = 'public' AND pg_get_userbyid(p.proowner) <> $1
-          ORDER BY p.proname
-        SQL
-        functions.each do |row|
-          db.exec("ALTER FUNCTION #{db.quote_ident(row['proname'])}(#{row['args']}) OWNER TO #{quoted}")
-        end
-        done << "#{functions.ntuples} function(s) in public -> #{role}" if functions.ntuples.positive?
-      end
-
-      def ledger_report(database, role, done, skipped)
-        lines = ["#{database} is #{role}'s"]
-        done.each { |line| lines << "  did:     #{line}" }
-        skipped.each { |line| lines << "  already: #{line}" }
-        lines << "  bind it: database \"postgres://#{role}@localhost/#{database}\"" if done.any?
-        lines.join("\n")
-      end
-
       def exists?(admin, database)
         admin.exec_params("SELECT 1 FROM pg_database WHERE datname = $1", [database]).ntuples.positive?
       end

data/lib/hecks/hecks/adapters/process_pool.rb

@@ -35,6 +35,10 @@ module Hecks
       # Signals passed on to a running child's process group.
       FORWARDED = %w[INT TERM HUP QUIT].freeze
 
+      # The flags of a sweep, and the fields of the record that fill them.
+      SWEEP_FLAGS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers,
+                      "--adapter" => :adapter }.freeze
+
       class << self
         # @return [#call, nil] runs a child given `(command, env, chdir)` and answers a `Finished`;
         #   a spec replaces it so nothing is started
@@ -54,18 +58,9 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `report:` what the sweep printed
       # @raise [ConsoleCapture::Failure] when the sweep found something, or could not run
       def sweep(**held)
-        if plain(held[:domain]).nil? && !RustWorkspace.new.checkout?
-          raise ConsoleCapture::Failure, "name a domain (hecks fuzz <domain>): sweeping every domain " \
-                                         "needs a hecks checkout"
-        end
-
-        command = [RbConfig.ruby, "-I", LIB, "-e", ENTRY, "--"]
-        command << plain(held[:domain]) if plain(held[:domain])
-        { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers, "--adapter" => :adapter }.each do |flag, key|
-          command.push(flag, plain(held[key]).to_s) unless plain(held[key]).nil?
-        end
+        refuse_unnamed_sweep(held)
 
-        answer(run(command))
+        answer(run([RbConfig.ruby, "-I", LIB, "-e", ENTRY, "--", *sweep_words(held)]))
       end
 
       # Starts a child, forwards interrupts to it, and waits for it to end.
@@ -79,27 +74,64 @@ module Hecks
         return starter.call(command, env, chdir) if starter
 
         output = Tempfile.new("process-pool")
+        status = start_and_wait(command, env, spawn_options(output, chdir))
+        Finished.new(File.read(output.path), status)
+      rescue Errno::ENOENT => e
+        Finished.new(e.message, Struct.new(:success?, :exitstatus).new(false, 127))
+      ensure
+        output&.close!
+      end
+
+      private
+
+      # The refusal for a sweep of every domain outside a checkout.
+      def refuse_unnamed_sweep(held)
+        return unless plain(held[:domain]).nil? && !RustWorkspace.new.checkout?
+
+        raise ConsoleCapture::Failure, "name a domain (hecks fuzz <domain>): sweeping every domain " \
+                                       "needs a hecks checkout"
+      end
+
+      # The words after `--`: the domain when named, then each flag the record names.
+      def sweep_words(held)
+        words = []
+        words << plain(held[:domain]) if plain(held[:domain])
+        SWEEP_FLAGS.each { |flag, key| words.push(flag, plain(held[key]).to_s) unless plain(held[key]).nil? }
+        words
+      end
+
+      # The options a child is spawned with: its own process group, its output in `output`.
+      def spawn_options(output, chdir)
         options = { pgroup: true, out: output, err: output }
         options[:chdir] = chdir if chdir
-        # Traps go in before the spawn, so a signal that lands while the child is starting is held
-        # and passed on the moment its pid is known, instead of orphaning it.
+        options
+      end
+
+      # Starts the child and waits for it, passing on the signals sent to this process meanwhile.
+      # Traps go in before the spawn, so a signal that lands while the child is starting is held
+      # and passed on the moment its pid is known, instead of orphaning it.
+      #
+      # @return [Process::Status] how the child ended
+      def start_and_wait(command, env, options)
         pid = nil
         held = []
-        previous = FORWARDED.to_h do |name|
-          [name, trap(name) { pid ? forward(name, pid) : held << name }]
-        end
+        previous = trap_forwarded(held) { pid }
         pid = spawn(env, *command, **options)
         held.each { |name| forward(name, pid) }
-        _, status = Process.wait2(pid)
-        Finished.new(File.read(output.path), status)
-      rescue Errno::ENOENT => e
-        Finished.new(e.message, Struct.new(:success?, :exitstatus).new(false, 127))
+        Process.wait2(pid).last
       ensure
         previous&.each { |name, handler| trap(name, handler) }
-        output&.close!
       end
 
-      private
+      # Traps every forwarded signal, answering the handlers it replaced.
+      #
+      # @param held [Array<String>] collects the signals that arrive before the pid is known
+      # @yield answers the child's pid, or nil while it is still starting
+      def trap_forwarded(held, &)
+        FORWARDED.to_h do |name|
+          [name, trap(name) { (pid = yield) ? forward(name, pid) : held << name }]
+        end
+      end
 
       def forward(name, pid)
         Process.kill(name, -pid)

data/lib/hecks/hecks/adapters/rust_toolchain.rb

@@ -139,10 +139,8 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `report:` what the benchmark printed
       # @raise [ConsoleCapture::Failure] when it could not run, or the install has no Rust workspace
       def measure(**held)
-        flags = BENCH_FLAGS.filter_map { |flag, key| [flag, plain(held[key]).to_s] unless plain(held[key]).nil? }
-        env = (self.class.workspace || RustWorkspace.new).environment.merge("HECKS_NO_3_0_NOTICE" => "1")
-        command = [RbConfig.ruby, "-I", LIB, "-e", BENCH, "--", *flags.flatten]
-        finished = (self.class.pool || ProcessPool.new).run(command, env: env)
+        command = [RbConfig.ruby, "-I", LIB, "-e", BENCH, "--", *bench_flags(held)]
+        finished = (self.class.pool || ProcessPool.new).run(command, env: bench_environment)
         raise ConsoleCapture::Failure, finished.output.strip unless finished.ok?
 
         { report: { value: finished.output } }
@@ -168,6 +166,16 @@ module Hecks
 
       private
 
+      # The environment the benchmark runs in: the Rust workspace's, without the 3.0 notice.
+      def bench_environment
+        (self.class.workspace || RustWorkspace.new).environment.merge("HECKS_NO_3_0_NOTICE" => "1")
+      end
+
+      # The benchmark's flags, each with its value, for those the record names.
+      def bench_flags(held)
+        BENCH_FLAGS.filter_map { |flag, key| [flag, plain(held[key]).to_s] unless plain(held[key]).nil? }.flatten
+      end
+
       def child(ask, argv)
         result = run(ask, argv)
         raise ConsoleCapture::Failure, message_of(result) unless result.ok?

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -40,9 +40,7 @@ module Hecks
       #   a duplicate path), a path or the extension is refused, or under `check` a file is out
       #   of date
       def project(**held)
-        flags = FLAGS.filter_map { |flag, key| "--#{flag}=#{located(key, held[key])}" unless plain(held[key]).nil? }
-        flags << "--check" if plain(held[:check]) == true
-        result = Codebase::RubyChild.new(Codebase::Tree.new).capture(SCRIPTS.fetch(:project), *flags,
+        result = Codebase::RubyChild.new(Codebase::Tree.new).capture(SCRIPTS.fetch(:project), *project_flags(held),
                                                                      located(:domain, held[:domain]))
         raise ConsoleCapture::Failure, message_of(result) unless result.ok?
 
@@ -62,10 +60,7 @@ module Hecks
       #   cannot be read, or the two differ; the message is the report
       def compare(**held)
         edge = edge_of(located(:domain, held[:domain]), located(:template, held[:template]))
-        live = live_configuration(held)
-        live_edge = Projections::Site::LiveEdge
-        comparison = live_edge.new(edge, live, expect_new: words(held[:expect_new]),
-                                               refs:       live_edge.refs_from(plain(held[:refs]))).call
+        comparison = compared(edge, live_configuration(held), held)
         raise ConsoleCapture::Failure, comparison.to_s unless comparison.clean?
 
         { output: { value: comparison.to_s } }
@@ -73,6 +68,20 @@ module Hecks
 
       private
 
+      # The flags `project_site` is run with: each the record names, and `--check` when asked.
+      def project_flags(held)
+        flags = FLAGS.filter_map { |flag, key| "--#{flag}=#{located(key, held[key])}" unless plain(held[key]).nil? }
+        flags << "--check" if plain(held[:check]) == true
+        flags
+      end
+
+      # The comparison of the project's edge with the live configuration.
+      def compared(edge, live, held)
+        live_edge = Projections::Site::LiveEdge
+        live_edge.new(edge, live, expect_new: words(held[:expect_new]),
+                                  refs:       live_edge.refs_from(plain(held[:refs]))).call
+      end
+
       # The project's checked edge, read the way `project_site` reads it.
       def edge_of(root, template = nil)
         registry = nil

data/lib/hecks/hecks/adapters/terminal.rb

@@ -40,7 +40,7 @@ module Hecks
         launcher = self.class.launcher
         launcher ? CLI::Console.call(domain, launcher: launcher) : CLI::Console.call(domain)
 
-        { output: { value: "console session ended (#{domain || 'pizzas'})" } }
+        { output: { value: "console session ended (#{domain || "pizzas"})" } }
       end
 
       # Hands the process over to the MCP door until the client closes stdin. The door writes its
@@ -52,14 +52,7 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when the process is not set up for stdio: the door
       #   refused to start, and said why on stderr
       def serve(**held)
-        argv = plain(held[:stdio]) ? ["--stdio"] : []
-        server = self.class.server
-        if server
-          server.call(argv)
-        else
-          require "hecks/cli/mcp"
-          CLI::Mcp.call(argv)
-        end
+        run_door(plain(held[:stdio]) ? ["--stdio"] : [])
 
         { output: { value: "mcp door closed" } }
       rescue SystemExit => e
@@ -83,6 +76,17 @@ module Hecks
 
       private
 
+      # Hands the process to the server a spec set, or else to the real MCP door.
+      def run_door(argv)
+        server = self.class.server
+        if server
+          server.call(argv)
+        else
+          require "hecks/cli/mcp"
+          CLI::Mcp.call(argv)
+        end
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end