hecks 3.9.1 → 3.11.0

data/lib/hecks/hecks/adapters/rehearsal/postgres_store.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "digest"
+require "open3"
+require "uri"
+require_relative "declaration"
+require_relative "postgres_reading"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The data copy as a throwaway database on the server the world's `connection_env` names.
+      #
+      # `empty` and `dump` create a database of this run's own (`hecks_rehearsal_<token>`) and
+      # restore the dump into it; `readonly_copy` reads a database somebody else made, as it is,
+      # in a read-only session, and never creates or drops one. A database is isolated, not a
+      # schema, because a dump carries its own schema names. The name derives from the run key, so
+      # every ask of one rehearsal reaches the same database and a dropped one is dropped once.
+      class PostgresStore
+        include PostgresReading
+
+        PREFIX = "hecks_rehearsal_"
+        NAME = /\A#{PREFIX}[0-9a-f]{16}\z/
+
+        # @param declaration [Declaration] a `postgres` declaration
+        # @param run [String] the rehearsal's key
+        # @param protected_databases [Array<String>] databases the domain's own world names
+        def initialize(declaration, run, protected_databases: [])
+          @declaration = declaration
+          @run = run
+          @protected = protected_databases
+        end
+
+        # @return [String] the database this rehearsal reads
+        def database_name
+          return URI.parse(server_url).path.delete_prefix("/") if @declaration.mode == "readonly_copy"
+
+          "#{PREFIX}#{Digest::SHA256.hexdigest(@run)[0, 16]}"
+        end
+
+        # Creates the database and restores the dump, or checks the copy is reachable. A failure
+        # leaves nothing behind.
+        #
+        # @return [void]
+        # @raise [Refused] if the server refuses, or the restore does
+        def prepare!
+          return reach_copy! if @declaration.mode == "readonly_copy"
+
+          discard!
+          admin { |db| db.exec("CREATE DATABASE #{db.quote_ident(database_name)}") }
+          restore! if @declaration.mode == "dump"
+        rescue Refused, PG::Error => e
+          discard!
+          raise e.is_a?(Refused) ? e : Refused.new(e.message.strip)
+        end
+
+        # Drops the throwaway database. A copy somebody else made is never dropped, and one the
+        # world asked to keep is refused here, so the run records why it stands.
+        #
+        # @return [void]
+        # @raise [Refused] if the world's `drop_after` is false and a database stands
+        def drop!
+          return if @declaration.mode == "readonly_copy" || !NAME.match?(database_name)
+          raise Refused, "kept #{database_name}: the world's drop_after is false" unless @declaration.drop_after
+
+          discard!
+        end
+
+        # @return [String] a URL for the database this rehearsal reads
+        def url
+          uri = URI.parse(server_url)
+          uri.path = "/#{database_name}"
+          uri.to_s
+        end
+
+        private
+
+        def discard!
+          return unless NAME.match?(database_name)
+
+          admin { |db| db.exec("DROP DATABASE IF EXISTS #{db.quote_ident(database_name)} WITH (FORCE)") }
+        rescue Refused, PG::Error
+          nil
+        end
+
+        def server_url
+          value = @declaration.connection
+          return value if value.match?(%r{\Apostgres(ql)?://})
+
+          raise Refused, "#{@declaration.connection_env} must hold a postgres:// URL"
+        end
+
+        def admin
+          require "pg"
+          db = PG.connect(server_url)
+          yield db
+        ensure
+          db&.close
+        end
+
+        def reach_copy!
+          raise Refused, "readonly_copy names a database the domain's own world persists to" if @protected.include?(url)
+
+          admin { |db| db.exec("SELECT 1") }
+        end
+
+        # argv arrays and PG* variables: no shell, and no password on a command line.
+        def restore!
+          file = @declaration.dump
+          raise Refused, "no such dump #{file.inspect}" unless File.file?(file)
+
+          _out, err, status = Open3.capture3(restore_env, *restore_argv(file))
+          raise Refused, "restoring the dump failed: #{err.strip.lines.first}" unless status.success?
+        end
+
+        def restore_argv(file)
+          return ["psql", "--no-psqlrc", "-v", "ON_ERROR_STOP=1", "-d", database_name, "-f", file] if file.end_with?(".sql")
+
+          ["pg_restore", "--no-owner", "--no-privileges", "-d", database_name, file]
+        end
+
+        def restore_env
+          uri = URI.parse(server_url)
+          { "PGHOST" => uri.host, "PGPORT" => uri.port&.to_s, "PGUSER" => uri.user, "PGPASSWORD" => uri.password }.compact
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/rows.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The mint audit's refusals as report rows: `Aggregate#id`, the rule that refused, and the
+      # audit's own wording, capped, with the total of them all.
+      module Rows
+        # How many rows a report holds; the total counts the rest.
+        CAP = 50
+
+        ROW = /\A([^#:]+)#([^:]+): (.*)\z/m
+
+        module_function
+
+        # @param violations [Array<String>] the audit's refusals, `Aggregate#id: wording`
+        # @return [Array(Array<Hash>, Integer)] the first `CAP` rows, and how many there were
+        def from(violations)
+          [violations.first(CAP).map { |text| row(text) }, violations.size]
+        end
+
+        # @param text [String] one refusal
+        # @return [Hash] `aggregate`, `id`, `rule`, `wording`
+        def row(text)
+          match = ROW.match(text)
+          aggregate, id, wording = match ? match.captures : ["(edge)", "-", text]
+          { aggregate: aggregate, id: id, rule: rule(wording), wording: wording }
+        end
+
+        # @param wording [String] a refusal's words
+        # @return [String] `lifecycle`, `reference` or `value`
+        def rule(wording)
+          return "lifecycle" if wording.include?("lifecycle never reaches")
+          return "reference" if wording.include?("reference transform") || wording.include?("id set changed")
+
+          "value"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/rust_audit.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "hecks/projector/exporter"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The Rust host's mint audit (`reference_validate`), run over the translated rows through the
+      # `validate_harness` binary, as the second engine of a rehearsal.
+      #
+      # The binary is found by `HECKS_VALIDATE_HARNESS`, else under `rust/host/target` of the
+      # checkout this gem runs from (`cargo build --bin validate_harness`); a rehearsal never
+      # builds it. Without one the engine is reported as not run.
+      class RustAudit
+        # @!attribute [r] ran
+        #   @return [Boolean] whether the harness answered
+        # @!attribute [r] violations
+        #   @return [Array<String>] its refusals, `Aggregate#id: wording`
+        # @!attribute [r] note
+        #   @return [String] why it did not run, or what it ran over
+        # @!attribute [r] rows
+        #   @return [Integer] how many rows it was given (zero when it did not run)
+        Result = Struct.new(:ran, :violations, :note, :rows, keyword_init: true)
+
+        # @return [String, nil] the harness binary, when one stands
+        def self.binary
+          root = File.expand_path("../../../../..", __dir__)
+          built = %w[debug release].map { |profile| "#{root}/rust/host/target/#{profile}/validate_harness" }
+          [ENV.fetch("HECKS_VALIDATE_HARNESS", nil), *built].compact.find { |path| File.executable?(path) }
+        end
+
+        # @param subject [Subject] the loaded domain, whose IR the audit is held to
+        # @param states [Hash{String => Hash{String => Hash}}] aggregate name, then id, then state
+        # @return [Result] what the harness refused, or why it did not run
+        def self.call(subject, states)
+          path = binary
+          return new(nil, subject).stood_down("no validate_harness built: cargo build --bin validate_harness") unless path
+
+          new(path, subject).call(states)
+        end
+
+        # @param path [String, nil] the harness binary
+        # @param subject [Subject] the loaded domain
+        def initialize(path, subject)
+          @path = path
+          @subject = subject
+        end
+
+        # @param states [Hash] aggregate name, id, state
+        # @return [Result] the harness's answer
+        def call(states)
+          cases = states.flat_map { |name, rows| rows.map { |id, state| case_for(name, id, state) } }
+          out, err, status = Open3.capture3(@path, stdin_data: JSON.generate("ir" => ir, "cases" => cases))
+          return stood_down("validate_harness failed: #{err.lines.first&.strip}") unless status.success?
+
+          answered(out, cases.size)
+        end
+
+        # @param note [String] why the engine did not run
+        # @return [Result] an answer that refused nothing
+        def stood_down(note) = Result.new(ran: false, violations: [], note: note, rows: 0)
+
+        private
+
+        def answered(out, rows)
+          Result.new(ran: true, violations: refusals(out), note: "ran over #{rows} rows", rows: rows)
+        end
+
+        def ir = Projector::Exporter.call(@subject.held.registry).fetch(@subject.bluebook.name)
+
+        def case_for(name, id, state)
+          { "aggregate" => name, "id" => id, "state" => JSON.parse(JSON.generate(state)) }
+        end
+
+        def refusals(out)
+          JSON.parse(out).fetch("results").flat_map { |result| result["violations"] || [result["error"]].compact }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/subject.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+require_relative "environment"
+require_relative "../journal_store/edge_audit"
+require_relative "../journal_store/held_domain"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The domain a rehearsal is run on: loaded as the era tools load it, with nothing bound or
+      # booted, so no persistence binding of the domain's own is reached.
+      class Subject
+        # The domain did not load: the answer a rehearsal gives is `cannot_boot`, with the reason.
+        class CannotBoot < StandardError; end
+
+        attr_reader :held, :declaration, :environment
+
+        # @param path [String] the domain directory
+        # @return [Subject] the loaded subject, with its world's declaration checked
+        # @raise [CannotBoot] if the directory is absent, declares no bluebook or does not load
+        # @raise [Refused] if the world's `rehearsed_by` is absent or wrong
+        def self.open(path)
+          environment = choose_environment(path)
+          held = load(path, environment)
+          new(held, Declaration.from_world(held.registry.world(held.bluebook.name), held.directory), environment)
+        end
+
+        # Whatever stops a domain from loading is a reason it cannot boot, a script error included.
+        # A missing bind names the environment that was loaded and the file it came from.
+        #
+        # @api private
+        def self.load(path, environment)
+          JournalStore::HeldDomain.open(path, environment: environment.overlay)
+        rescue Runtime::WiringError => e
+          raise CannotBoot, "#{e.message} The rehearsal loaded #{environment}; overlays this domain " \
+                            "holds: #{environment.available_words}. " \
+                            "Name one with `environment \"...\"` in rehearsed_by, or HECKS_PROJECT_ENVIRONMENT."
+        rescue StandardError, ScriptError => e
+          raise CannotBoot, e.message
+        end
+        private_class_method :load
+
+        # The overlay the world names, read before the domain loads so the load can use it.
+        #
+        # @api private
+        def self.choose_environment(path)
+          loading = Ports::Loading.bootstrap
+          directory = loading.bluebook_directory(path)
+          Environment.resolve(declared_environment(loading, directory), directory)
+        rescue StandardError, ScriptError
+          Environment.resolve(nil, path.to_s)
+        end
+        private_class_method :choose_environment
+
+        # @api private
+        def self.declared_environment(loading, directory)
+          registry = Runtime::Registry.new(root: File.dirname(directory))
+          Hecks.with_registry(registry) do
+            loading.load_library
+            loading.load_each(directory, %w[*.world])
+          end
+          registry.worlds.values.filter_map { |world| world.for_verb("rehearsed_by")[:environment] }.first
+        rescue StandardError, ScriptError
+          nil
+        end
+        private_class_method :declared_environment
+
+        # @param held [JournalStore::HeldDomain] the loaded domain
+        # @param declaration [Declaration] what its world says about the data copy
+        # @param environment [Environment] the overlay the domain was loaded under
+        def initialize(held, declaration, environment)
+          @held = held
+          @declaration = declaration
+          @environment = environment
+        end
+
+        # @return [Bluebook::Chapter] the domain's bluebook as it stands
+        def bluebook = held.bluebook
+
+        # @return [String] the label the shape a mint would hold has
+        def label = Runtime::StorageShape.mint_label(bluebook)
+
+        # @return [String] the domain's bluebook directory
+        def directory = held.directory
+
+        # The edge that leads one era's label to the shape's label.
+        #
+        # @param from [String] the held era's label
+        # @return [Bluebook::Translation, nil] the edge; nil when none is declared
+        def edge_from(from)
+          held.registry.translations.find { |t| t.domain == bluebook.name && t.from == from && t.to == label }
+        end
+
+        # @return [Array<String>] the persisted databases the domain's own world names, which a
+        #   rehearsal must never be pointed at
+        def declared_databases
+          blocks = held.registry.world(bluebook.name)&.settings || {}
+          blocks.select { |key, _| key.to_s.start_with?("persisted_by") }.values.filter_map { |block| block[:database] }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "rehearsal/declaration"
+require_relative "rehearsal/rows"
+require_relative "rehearsal/subject"
+require_relative "rehearsal/memory_store"
+require_relative "rehearsal/postgres_store"
+require_relative "rehearsal/inquiry"
+
+module Hecks
+  module Adapters
+    # Helpers the two rehearsal port adapters (`RehearsalStore`, `RehearsalSubject`) share.
+    module Rehearsal
+      module_function
+
+      # The Hecks this process runs, as `release+commit` when a checkout can name its commit.
+      #
+      # @return [String] `3.9.0`, or `3.9.0+bb8e41d`
+      def host_version
+        commit = checkout_commit
+        commit ? "#{Hecks::VERSION}+#{commit[0, 7]}" : Hecks::VERSION.to_s
+      end
+
+      # @param pin [String, nil] a release or a commit prefix the run must be on
+      # @return [void]
+      # @raise [Refused] if this process is not on the pin
+      def check_pin!(pin)
+        return if pin.nil? || pin.empty? || pin == Hecks::VERSION.to_s || checkout_commit.to_s.start_with?(pin)
+
+        raise Refused, "this is Hecks #{host_version}, not the pin #{pin}: run the rehearsal from the pinned install"
+      end
+
+      # @param subject [Subject] the loaded domain
+      # @param run [String] the rehearsal's key
+      # @return [MemoryStore, PostgresStore] the store its world declares
+      def store_for(subject, run)
+        declaration = subject.declaration
+        return MemoryStore.new(declaration) if declaration.kind == "memory"
+
+        PostgresStore.new(declaration, run, protected_databases: subject.declared_databases)
+      end
+
+      # @return [String, nil] the commit of the checkout this gem runs from
+      def checkout_commit
+        root = File.expand_path("../../../..", __dir__)
+        out, status = Open3.capture2("git", "-C", root, "rev-parse", "HEAD", err: File::NULL)
+        status.success? ? out.strip : nil
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal_store.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/rehearsal_store"
+
+Hecks.adapter "RehearsalStore" do
+  port "RehearsalStore"
+end

data/lib/hecks/hecks/adapters/rehearsal_store.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "rehearsal"
+
+module Hecks
+  module Adapters
+    # The `RehearsalStore` port's adapter: the copy of a domain's data its own world names, which
+    # prepares itself when surveyed, runs the mint's audit over itself when examined, and is
+    # dropped when it has answered, whichever way it answers.
+    #
+    # The strategy (`memory` or `postgres`) is the one the subject's `.world` declares with
+    # `rehearsed_by`, never an argument. Nothing is written to the subject's own databases: no era
+    # is held or named, no table provisioned, no command dispatched. The copy is dropped here, in
+    # the same ask that last needs it, so no reaction that fails to arrive can leave one behind.
+    class RehearsalStore
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Prepares the copy, loads the domain against it, and reads where its shape stands.
+      #
+      # @param held [Hash] the record: `domain`, `run` and `pin`
+      # @return [Hash] the shape facts and what the copy holds, or `booted: false` with why the
+      #   domain did not load
+      # @raise [Rehearsal::Refused] if the pin, the world's declaration or the copy is refused
+      def survey(**held)
+        Rehearsal.check_pin!(plain(held[:pin]))
+        subject = Rehearsal::Subject.open(plain(held[:domain]))
+        store = Rehearsal.store_for(subject, plain(held[:run]))
+        store.prepare!
+        guarded(store) { surveyed(subject, store) }
+      rescue Rehearsal::Subject::CannotBoot => e
+        { booted: { value: false }, boot_error: { value: e.message } }
+      end
+
+      # Runs the mint's audit over the copy, then drops it.
+      #
+      # @param held [Hash] the record: `domain` and `run`
+      # @return [Hash] the edge facts, every refused row, what was not checked, and whether the
+      #   copy was dropped
+      def examine(**held)
+        subject = Rehearsal::Subject.open(plain(held[:domain]))
+        store = Rehearsal.store_for(subject, plain(held[:run]))
+        facts = guarded(store) { Rehearsal::Inquiry.new(subject, store).examine }
+        facts.merge(release(store))
+      rescue Rehearsal::Subject::CannotBoot => e
+        raise Rehearsal::Refused, e.message
+      end
+
+      private
+
+      # A copy that holds nothing is answered at once, so it is dropped here: no examination
+      # follows to drop it. Any other copy stands until it is examined.
+      def surveyed(subject, store)
+        facts = Rehearsal::Inquiry.new(subject, store).survey
+        standing = { released: { value: false }, kept: { value: "" } }
+        facts.merge(facts[:copy_empty][:value] ? release(store) : standing)
+      end
+
+      # Runs the block; when it raises, the copy is dropped before the error goes on.
+      def guarded(store)
+        yield
+      rescue StandardError
+        release(store)
+        raise
+      end
+
+      def release(store)
+        store.drop!
+        { released: { value: true }, kept: { value: "" } }
+      rescue Rehearsal::Refused, StandardError => e
+        { released: { value: false }, kept: { value: e.message } }
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require_relative "../../../projections/site/role_probe"
+
+module Hecks
+  module Adapters
+    class SiteToolchain
+      # Dispatches each role-declaring command to a host with no role and no actor, and reports
+      # whether the host refused the caller.
+      #
+      # A host that does not enforce roles would run the command, so this talks only to a host on
+      # this machine: the one a spec or a CI job started for the purpose.
+      class RoleProber
+        # The addresses that name this machine.
+        LOOPBACK = %w[localhost 127.0.0.1 ::1 [::1]].freeze
+
+        # Seconds to wait to connect to the host, and again for its answer.
+        TIMEOUT = 10
+
+        # The failures of the network that fail one check rather than the whole run.
+        NETWORK = [SystemCallError, Timeout::Error, SocketError, JSON::ParserError].freeze
+
+        # @param checks [Array<Projections::Site::RoleProbe::Check>] the commands to dispatch
+        # @param base [String] the host's scheme, host and port
+        # @raise [ConsoleCapture::Failure] when the host is not on this machine
+        def initialize(checks, base:)
+          @checks = checks
+          @uri = URI.parse(base)
+          return if LOOPBACK.include?(@uri.host)
+
+          raise ConsoleCapture::Failure, "roles are checked against a host on this machine, not #{@uri.host}: " \
+                                         "a host that does not enforce roles would run each command"
+        end
+
+        # @return [Array<(String, Integer)>] the report, one line per command ending in the count,
+        #   and how many failed; a command whose synthesized arguments the host refused is counted
+        #   as unchecked, not failed
+        def call
+          lines = @checks.map { |check| judged(check) }
+          failed = lines.count { |_, state| state == :failed }
+          unchecked = lines.count { |_, state| state == :unchecked }
+          summary = "#{lines.size} commands, #{failed} failed, #{unchecked} unchecked"
+          [lines.map(&:first).append(summary).join("\n"), failed]
+        end
+
+        private
+
+        def judged(check)
+          answer = answer_to(check)
+          return [line(check, "unchecked: the host refused the arguments before the role"), :unchecked] if unchecked?(answer)
+
+          why = Projections::Site::RoleProbe.verdict(check, answer)
+          [line(check, why ? "FAILED: #{why}" : "ok"), why ? :failed : :ok]
+        rescue *NETWORK => e
+          [line(check, "FAILED: #{e.class}: #{e.message}"), :failed]
+        end
+
+        def unchecked?(answer) = Projections::Site::RoleProbe.unchecked?(answer)
+
+        def line(check, outcome) = "  #{check.verb} (#{check.role}) is refused with no role... #{outcome}"
+
+        def answer_to(check)
+          request = Net::HTTP::Post.new(URI.join(@uri.to_s, "/dispatch"), "Content-Type" => "application/json")
+          request.body = JSON.generate(verb: check.verb, with: check.arguments)
+          JSON.parse(connection.request(request).body)
+        end
+
+        def connection
+          Net::HTTP.new(@uri.host, @uri.port).tap do |http|
+            http.open_timeout = http.read_timeout = TIMEOUT
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -9,6 +9,7 @@ require "hecks/tools"
 require "hecks/tools/site_routes"
 require "hecks/projections/site/live_edge"
 require_relative "site_toolchain/prober"
+require_relative "site_toolchain/role_prober"
 
 module Hecks
   module Adapters
@@ -23,7 +24,8 @@ module Hecks
       SCRIPTS = { project: "project_site" }.freeze
 
       # The tool's flag for each `SiteProjection` field that takes a value.
-      FLAGS = { "out" => :out, "template" => :template, "cms" => :cms, "root" => :root, "extension" => :extension }.freeze
+      FLAGS = { "out" => :out, "template" => :template, "cms" => :cms, "root" => :root, "editor" => :editor,
+                "extension" => :extension }.freeze
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
@@ -35,7 +37,7 @@ module Hecks
       # Writes a project's `routes.ts` from its declared route table, or with `check` only compares.
       #
       # @param held [Hash] the `SiteProjection` record: `domain`, and `out`, `template`, `cms`,
-      #   `root`, `extension` and `check` when set
+      #   `root`, `editor`, `extension` and `check` when set
       # @return [Hash{Symbol => Hash}] `output:` one line per file written or found current
       # @raise [ConsoleCapture::Failure] when the route table is refused (an unknown cache class,
       #   a duplicate path), a path or the extension is refused, or under `check` a file is out
@@ -84,6 +86,23 @@ module Hecks
         { output: { value: report } }
       end
 
+      # Dispatches every command a project declares a role for to a host with no role and no actor,
+      # and checks the host refuses each as `Unauthorized`. The host must be on this machine and
+      # enforcing roles (`HECKS_ROLE_ENFORCEMENT=enforce`); one that is not would run the commands.
+      #
+      # @param held [Hash] the `SiteProjection` record: `domain`, the project that declares the
+      #   commands, and `url`, the host's base address
+      # @return [Hash{Symbol => Hash}] `output:` one line per command, ending in the count
+      # @raise [ConsoleCapture::Failure] when the host is not on this machine, or a command is not
+      #   refused for its role; the message is the report
+      def roles(**held)
+        checks = Projections::Site::RoleProbe.checks(registry_of(located(:domain, held[:domain])))
+        report, failed = RoleProber.new(checks, base: base_url(plain(held[:url]))).call
+        raise ConsoleCapture::Failure, report if failed.positive?
+
+        { output: { value: report } }
+      end
+
       private
 
       # The scheme, host and port of an http(s) address.
@@ -121,12 +140,18 @@ module Hecks
       # The project's checked route table.
       def table_of(root) = read_table(root).last
 
-      # The registry, chapter and checked table of the project at `root`.
-      def read_table(root)
+      # The registry the project at `root` boots into.
+      def registry_of(root)
         registry = nil
         outcome = ConsoleCapture.capture { registry = Tools::SiteRoutes.registry_for(root) }
         raise ConsoleCapture::Failure, outcome.output.strip unless outcome.ok?
 
+        registry
+      end
+
+      # The registry, chapter and checked table of the project at `root`.
+      def read_table(root)
+        registry = registry_of(root)
         chapter = Projections::Site::Table.chapter(registry)
         [registry, chapter, Projections::Site::Table.read(chapter, registry: registry)]
       rescue Projections::Site::Table::Invalid => e