hecks 2.7.0 → 2.8.0

data/lib/hecks/cli/model_check.rb

@@ -0,0 +1,270 @@
+require_relative "../../hecks"
+require_relative "../bluebook/model_check"
+
+module Hecks
+  module CLI
+    # The command behind `bin/model_check` and `hecks model_check`: static analysis
+    # over the IR, printed per domain, exiting non-zero when any error-severity
+    # finding is left.
+    #
+    # It finds unreachable lifecycle states, transitions nothing can fire, saga
+    # states no handler chain reaches, a compensation whose `from_state` is
+    # unreachable, dispatches to a command that does not exist, and handlers
+    # listening for an event nothing emits. The runtime checks none of these: a dead
+    # transition never fires, in silence.
+    #
+    # ## Named domains, or the whole corpus
+    #
+    # Given domain paths, it boots each and runs one cross-domain check across all
+    # of them. Given none, it sweeps the repository's corpus (`Corpus.model_check_members`)
+    # and the language's own chapters; that needs `root:`, the repository, so an
+    # installed gem without one asks for a domain path instead.
+    #
+    # ## Options
+    #
+    # `--strict` makes a `rust_reserved_name` finding an error for every target, not
+    # only for those with a Cargo feature under `root`'s `rust/Cargo.toml`.
+    # `--profile client` adds `Bluebook::ModelCheck::ClientProfile`'s error findings.
+    module ModelCheck
+      # The directory the framework's own `.port` and `.adapter` files live under.
+      HECKS_DIR = File.expand_path("..", __dir__)
+
+      # How one run is configured: `strict` and `profile` from the command line,
+      # `rust_dir` from the root (nil without one).
+      Options = Struct.new(:strict, :profile, :rust_dir)
+
+      module_function
+
+      # Runs the model check `argv` describes and exits with its verdict.
+      #
+      # @param argv [Array<String>] `--strict`, `--profile NAME` and domain paths
+      # @param program [String] the name the usage message calls this command by
+      # @param root [String, nil] the repository root, for the corpus sweep and the
+      #   Rust-target check; nil when there is no checkout
+      # @return [void]
+      # @raise [SystemExit] always: 0 when clean, 1 with findings or a usage error,
+      #   2 for an unknown profile
+      def call(argv, program:, root: nil)
+        argv = argv.dup
+        strict = !argv.delete("--strict").nil?
+        profile = take_profile(argv)
+        unless profile.nil? || Bluebook::ModelCheck::PROFILES.include?(profile)
+          warn "unknown profile #{profile.inspect} (known: #{Bluebook::ModelCheck::PROFILES.join(', ')})"
+          exit 2
+        end
+
+        options = Options.new(strict, profile, root && File.join(root, "rust"))
+        ok = if argv.any? then check_domains(argv, options)
+             elsif root then check_corpus(root, options)
+             else abort "usage: #{program} [--strict] [--profile client] <domain> [<domain> …]"
+             end
+
+        puts
+        puts ok ? "No dead states, no unreachable protocol steps." : "THE MODEL HAS FINDINGS."
+        exit(ok ? 0 : 1)
+      end
+
+      # Reads `--profile client` or `--profile=client` and removes it from `argv`.
+      #
+      # @param argv [Array<String>] the arguments, changed in place
+      # @return [Symbol, nil] the requested profile, or nil when none was asked for
+      def take_profile(argv)
+        inline = argv.find { |arg| arg.start_with?("--profile=") }
+        index = argv.index("--profile")
+        return unless inline || index
+
+        name = inline ? inline.delete_prefix("--profile=") : argv[index + 1].to_s
+        argv.delete(inline) if inline
+        argv.slice!(index, 2) if index
+        name.to_sym
+      end
+
+      # Boots each named domain and examines them against one shared set of known
+      # domains and emitted events, so a cross-domain reaction between two of them
+      # is checked.
+      #
+      # @param domain_args [Array<String>] domain directory paths
+      # @param options [Options] the run's configuration
+      # @return [Boolean] true when every domain passes
+      def check_domains(domain_args, options)
+        booted = domain_args.map do |domain_arg|
+          [File.basename(domain_arg.chomp("/")), boot(bluebook_dir(domain_arg.chomp("/")) || domain_arg)]
+        end
+        examine_all(booted, options)
+      end
+
+      # Boots every corpus member once, then examines each against the set of names
+      # every member declares, then examines the language itself.
+      #
+      # Two passes over the same boots, because a single boot's own registry cannot
+      # answer whether a target domain exists anywhere in the corpus.
+      #
+      # @param root [String] the repository root
+      # @param options [Options] the run's configuration
+      # @return [Boolean] true when every member and the language pass
+      def check_corpus(root, options)
+        require_relative "../corpus"
+        targets = Corpus.model_check_members(root: root).map { |member| [member.stem, Corpus.source_of(member)] }
+        booted = targets.map { |name, source| [name, boot(source)] }
+        ok = examine_all(booted, options)
+        examine_language(options) && ok
+      end
+
+      # Boots one source into a fresh registry, with its sibling hecksagons so a
+      # policy bound from there is visible too.
+      #
+      # `root:` is the source's parent: a directory source is already the domain's
+      # own `bluebook/` folder, and without a root a member declaring
+      # `uses_embryonaut_bluebook` refuses with "needs a registry with a root to
+      # vendor from".
+      #
+      # @param source [String] a directory to boot (every bluebook within), or a
+      #   single `.bluebook` file path
+      # @return [Runtime::Registry] the registry populated with the booted bluebooks
+      def boot(source)
+        root = File.directory?(source) ? File.dirname(source) : nil
+        registry = Runtime::Registry.new(root: root)
+        Hecks.with_registry(registry) { load_source(source) }
+        registry
+      end
+
+      # @api private
+      def load_source(source)
+        Kernel.load(File.join(HECKS_DIR, "ports/persistence.port"))
+        Kernel.load(File.join(HECKS_DIR, "ports/extraction.port"))
+        Kernel.load(File.join(HECKS_DIR, "adapters/driven/memory.adapter"))
+        Kernel.load(File.join(HECKS_DIR, "adapters/driven/prism.adapter"))
+        folder = Adapters::Folder.new
+        if File.directory?(source)
+          folder.load_bluebooks(source)
+        else
+          folder.load_bluebooks(File.dirname(source), [File.basename(source)])
+        end
+
+        # A port attaches to its aggregate from the hecksagon, not the bluebook, so a
+        # deaf-policy check that never loads it would see a policy reacting to an
+        # event nothing appears to emit. A directory loads every `*.hecksagon` in it,
+        # as a real boot does. Recording a bind builds IR only, so no adapter needs to
+        # resolve here.
+        hecksagons = if File.directory?(source)
+                       Dir.glob(File.join(source, "*.hecksagon"))
+                     else
+                       [source.sub(/\.bluebook\z/, ".hecksagon")]
+                     end
+        hecksagons.each { |hecksagon| Kernel.load(hecksagon) if File.exist?(hecksagon) }
+      end
+
+      # @api private
+      def examine_all(booted, options)
+        known_domains = booted.flat_map { |_, registry| registry.bluebooks.keys + registry.hecksagons.keys }.to_set
+        global_emitted_events = booted.flat_map do |_, registry|
+          registry.bluebooks.values.flat_map { |chapter| Bluebook::ModelCheck.emitted_events(chapter) }
+        end.to_set
+
+        booted.reduce(true) do |all_ok, (name, registry)|
+          domain_passes?(name, registry, options,
+                         known_domains: known_domains, global_emitted_events: global_emitted_events) && all_ok
+        end
+      end
+
+      # Runs `Bluebook::ModelCheck` over one booted domain's chapters, prints its
+      # findings against the allowlist, and reports whether it passes.
+      #
+      # @param name [String] the domain's display name, for the header and the
+      #   `ALLOWED_FINDINGS` lookup
+      # @param registry [Runtime::Registry] a booted registry holding the domain's chapters
+      # @param options [Options] the run's configuration
+      # @param known_domains [Set<String>] every bluebook and hecksagon name booted this run
+      # @param global_emitted_events [Set<String>] every event any booted chapter emits
+      # @return [Boolean] false if an allowlist entry is stale; otherwise true when no
+      #   error-severity finding is left
+      def domain_passes?(name, registry, options, known_domains:, global_emitted_events:)
+        puts "── #{name}"
+
+        rust_target = rust_target?(name, options.rust_dir)
+        chapters = registry.bluebooks.values
+        findings = chapters.flat_map do |chapter|
+          Bluebook::ModelCheck.call(chapter, hecksagon: registry.hecksagon(chapter.name), known_domains: known_domains,
+                                             global_emitted_events: global_emitted_events,
+                                             rust_target: rust_target,
+                                             strict: options.strict, profile: options.profile)
+        end
+
+        allowed = Bluebook::ModelCheck::ALLOWED_FINDINGS.fetch(name, [])
+        matched, findings = findings.partition { |f| allowed.include?([f.kind, f.subject]) }
+        matched.each { |f| puts "   ALLOWLISTED  #{f}" }
+
+        stale = allowed - matched.map { |f| [f.kind, f.subject] }
+        unless stale.empty?
+          puts "   STALE ALLOWLIST ENTRIES (no longer found — remove them): #{stale.inspect}"
+          return false
+        end
+
+        passes?(findings, "   clean — #{chapters.size} chapter(s), no dead states, no unreachable protocol steps")
+      end
+
+      # Examines the language's own `Bluebook` and `World` chapters through
+      # `MetaValidator.grammar_registry`, the judged graph its conformance specs use,
+      # because any one grammar file booted alone is a fraction of the language.
+      #
+      # @param options [Options] the run's configuration
+      # @return [Boolean] true when neither chapter has an error-severity finding
+      def examine_language(options)
+        ok = true
+        ["Bluebook", "World"].each do |name|
+          chapter = Bluebook::MetaValidator.grammar_registry.bluebook(name)
+          next unless chapter
+
+          puts "── #{name} (the language itself)"
+          findings = Bluebook::ModelCheck.call(chapter, strict: options.strict, profile: options.profile)
+          ok = passes?(findings, "   clean — no dead states, no unreachable protocol steps") && ok
+        end
+        ok
+      end
+
+      # @api private
+      def passes?(findings, clean_line)
+        if findings.empty?
+          puts clean_line
+          return true
+        end
+
+        errors, warnings = findings.partition { |f| f.severity == :error }
+        puts "   #{errors.size} error(s), #{warnings.size} warning(s)"
+        findings.each { |f| puts "     #{f}" }
+        errors.empty?
+      end
+
+      # Says whether the domain has a Cargo feature, which makes a
+      # `rust_reserved_name` finding an error for it.
+      #
+      # The check reads `rust/Cargo.toml` through the repository-only fuzzing
+      # tooling, so it is loaded only when there is a `rust/` to read.
+      #
+      # @param name [String] the domain's display name
+      # @param rust_dir [String, nil] the repository's `rust/` directory; nil without a
+      #   checkout
+      # @return [Boolean] true when `rust_dir` declares a feature named after the domain
+      def rust_target?(name, rust_dir)
+        return false unless rust_dir
+
+        require_relative "../fuzzing/target_capabilities"
+        Fuzzing::TargetCapabilities.rust_feature?(name, rust_dir)
+      end
+
+      # The directory holding a domain's bluebooks: `<domain>/bluebook/` or the
+      # domain directory itself, the same rule `Corpus.bluebook_dir` applies.
+      #
+      # @param domain_path [String] a domain directory path
+      # @return [String, nil] the directory of the first `.bluebook` found, or nil when
+      #   neither place holds one
+      def bluebook_dir(domain_path)
+        [File.join(domain_path, "bluebook"), domain_path].each do |dir|
+          files = Dir[File.join(dir, "*.bluebook")]
+          return File.dirname(files.first) unless files.empty?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/cli/project_cli.rb

@@ -0,0 +1,123 @@
+require "fileutils"
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/project_cli` and `hecks project_cli`: writes a
+    # command-line launcher beside each domain, named after its bluebook, so
+    # `Hecks.bluebook "QualityControl"` in `qa/` becomes `qa/quality_control`.
+    #
+    # ## A launcher, not a CLI
+    #
+    # Each file is a dozen lines pinning one directory and handing over to
+    # `Facade::CliRunner`. The surface still comes from `Projector.call(:cli, …)` at
+    # the moment it runs, so editing a chapter changes the launcher's behaviour
+    # without regenerating anything. Re-run this when a domain is added or renamed.
+    #
+    # ## Beside the domain
+    #
+    # A domain's command line lives with the domain, so a folder is the whole unit.
+    # The launcher boots `__dir__`, and reaches `lib` by counting how deep the domain
+    # sits below the root, so no line knows where the checkout was cloned.
+    module ProjectCli
+      # Build output and other trees under a root that hold no domain a caller means.
+      IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
+
+      module_function
+
+      # Writes a launcher for each domain `argv` names, or for every domain under
+      # `root`.
+      #
+      # @param argv [Array<String>] domain paths relative to `root`; empty for all of them
+      # @param program [String] the name the generated header credits
+      # @param root [String] the directory domains are found under and paths resolve against
+      # @param remove_stale_bin [Boolean] whether to delete `root/bin/<name>`, where a
+      #   launcher for the same chapter would otherwise linger as a second front door
+      # @return [void]
+      def call(argv, program:, root:, remove_stale_bin: true)
+        wanted = argv.empty? ? domains(root) : argv.map { |path| path.delete_prefix("#{root}/").chomp("/") }
+
+        wanted.each do |path|
+          name  = bluebook_name(root, path) or next
+          snake = Naming.snake(name)
+          file  = File.join(root, path, snake)
+
+          File.write(file, launcher(path, name, program))
+          FileUtils.chmod("+x", file)
+          FileUtils.rm_f(File.join(root, "bin", snake)) if remove_stale_bin
+
+          puts "  #{path}/#{snake}  ->  #{name}"
+        end
+      end
+
+      # Finds every domain under `root` a launcher can be written for.
+      #
+      # @param root [String] the directory to search under
+      # @return [Array<String>] domain directory paths relative to `root`,
+      #   deduplicated and sorted
+      def domains(root)
+        folder = Adapters::Folder.new
+        Dir.glob(File.join(root, "**/*.hecksagon"))
+           .map { |path| folder.domain_root(File.dirname(path)) }
+           .compact
+           .map { |path| path.delete_prefix("#{root}/") }
+           .grep_v(IGNORED)
+           .uniq.sort
+      end
+
+      # Boots the domain to read its declared name, which comes from
+      # `Hecks.bluebook "…"` rather than the directory, so a domain renamed with
+      # `formerly_known_as` gets a launcher under its new name.
+      #
+      # @param root [String] the directory `path` is relative to
+      # @param path [String] a domain directory path
+      # @return [String, nil] the domain's declared bluebook name, or nil after warning
+      #   when it fails to boot
+      def bluebook_name(root, path)
+        Hecks.boot(File.join(root, path), install_facade: false).registry.bluebooks.keys.first
+      rescue StandardError => e
+        warn "  #{path}: cannot boot — #{e.message.lines.first.strip}"
+        nil
+      end
+
+      # Renders one domain's launcher.
+      #
+      # @param path [String] the domain directory path, relative to the root
+      # @param name [String] the domain's declared bluebook name
+      # @param program [String] the name the generated header credits
+      # @return [String] the launcher script's full source
+      def launcher(path, name, program)
+        snake = Naming.snake(name)
+        up    = "../" * path.count("/").succ
+
+        <<~RUBY
+          #!/usr/bin/env ruby
+
+          # #{name}'s command line — GENERATED by #{program}. Do not edit.
+          #
+          # A launcher, not a CLI: the verbs, their arguments and their refusals are
+          # projected from the bluebook beside it every time this runs, so a change
+          # to the chapter shows up here without re-minting anything.
+          #
+          #   #{path}/#{snake}                  every verb, and every question
+          #   #{path}/#{snake} <verb> --help    what it wants, and how it refuses
+
+          $LOAD_PATH.unshift File.expand_path("#{up}lib", __dir__)
+
+          require "hecks"
+
+          runtime = begin
+            Hecks.boot(__dir__, install_facade: false)
+          rescue StandardError => e
+            abort "cannot open #{name}: \#{e.message.lines.first.strip}"
+          end
+
+          text, status = Hecks::Facade::CliRunner.call(
+            runtime: runtime, argv: ARGV, program: "#{path}/#{snake}"
+          )
+          status.zero? ? puts(text) : abort(text)
+        RUBY
+      end
+    end
+  end
+end

data/lib/hecks/cli/project_diagrams.rb

@@ -0,0 +1,43 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/project_diagrams` and `hecks project_diagrams`: boots a
+    # domain, finds the chapter it names, and writes its Mermaid diagrams
+    # (`Projections::Diagrams`) under `docs/generated/diagrams/<chapter>/` below the
+    # root.
+    module ProjectDiagrams
+      module_function
+
+      # Projects and writes one chapter's diagrams, then lists what was written.
+      #
+      # @param argv [Array<String>] the domain path, then the chapter name
+      # @param program [String] the name the usage message calls this command by
+      # @param root [String] the directory `docs/generated/diagrams/` is written under
+      # @return [void]
+      # @raise [SystemExit] when either argument is missing
+      def call(argv, program:, root:)
+        usage = "usage: #{program} <domain-path> <ChapterName>"
+        domain_path  = argv[0] or abort usage
+        chapter_name = argv[1] or abort usage
+
+        runtime   = Hecks.boot(File.expand_path(domain_path, Dir.pwd))
+        chapter   = runtime.registry.bluebook(chapter_name)
+        hecksagon = runtime.registry.hecksagon(chapter_name)
+        directory = File.expand_path("docs/generated/diagrams/#{Naming.snake(chapter_name)}", root)
+
+        written = Projector.write(
+          Projector.call(:diagrams, bluebook: chapter, options: { hecksagon: hecksagon }),
+          directory, as: :files
+        )
+
+        if written.empty?
+          puts "#{chapter_name} declares no lifecycle, relationship, or dispatch to project yet"
+        else
+          puts "wrote #{written.size} diagram(s) to #{directory}:"
+          written.each { |path| puts "  #{path}" }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/run.rb

@@ -0,0 +1,219 @@
+require "json"
+require_relative "../../hecks"
+# ADR 0033 — a domain wired to PostgresEra needs this plugin loaded
+# explicitly; the era/lineage subsystem does not load with core.
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `bin/run` and `hecks run`: dispatches one verb from the
+    # command line, or executes a JSON step list and reports instances, events,
+    # refusals, reactions, sagas and query rows.
+    #
+    # ## Two forms, one argument
+    #
+    # `run bug.discover reference=BUG#1 severity=high …` needs no JSON. The verb
+    # tree, every argument, its declared type and every way the verb can refuse are
+    # projected out of the bluebook (`Projector::CliProjector`) and run by
+    # `Facade::CliRunner`, so this knows nothing about any domain and its help
+    # cannot go stale. The step-list form takes a script path, `-` for stdin, or the
+    # JSON itself, which is how the corpus scripts under `spec/corpus/` are run.
+    #
+    # ## Standing in a domain is enough
+    #
+    # `Adapters::Folder#domain_root` walks up for the nearest `.hecksagon`, so inside
+    # a domain the path can be left off. The first argument is a domain only when it
+    # is a directory.
+    module Run
+      module_function
+
+      # Runs `argv` as a verb invocation or a step list against a domain.
+      #
+      # @param argv [Array<String>] the arguments: an optional domain directory, then
+      #   a verb with `name=value` pairs, a script path, `-`, or inline JSON
+      # @param program [String] the name usage and help messages call this command by
+      # @return [void]
+      # @raise [SystemExit] on any refusal, usage error or unmet expectation, and
+      #   after the command-line form answers
+      def call(argv, program:)
+        usage = "usage: #{program} [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"
+        argv = argv.dup
+        here = Adapters::Folder.new.domain_root
+        domain = argv.first && File.directory?(argv.first) ? argv.shift : here
+        abort "no bluebook here — #{Dir.pwd} is not inside a domain. #{usage}" unless domain
+
+        # The command-line form answers unless the first argument is script-shaped,
+        # in which case the step-list form takes over.
+        cli_form(domain, argv, program) unless argv.first && script_shaped?(argv.first)
+
+        script = argv.first or abort usage
+        document = parse(read_source(script))
+        steps = document["steps"] or abort %(the script has no "steps" — #{usage})
+        report = execute(Hecks.boot(domain), steps)
+
+        # The run is reported before it is judged: an expectation that fails says
+        # what was wanted and never what happened, so the evidence goes to stdout
+        # first and every unmet expectation is collected rather than aborted on.
+        puts JSON.pretty_generate(report)
+        unmet = unmet_expectations(document["expectations"] || {}, report)
+        abort unmet.join("\n") unless unmet.empty?
+      end
+
+      # Boots `domain` and dispatches `argv` as a projected verb invocation, printing
+      # the result and exiting the process.
+      #
+      # **No fall-through**. This is reached only when the argument is not
+      # script-shaped, so a near miss deserves the runner's "did you mean" rather
+      # than the step-list form's "no such script".
+      #
+      # @param domain [String] the domain's directory path
+      # @param argv [Array<String>] the arguments after the domain, e.g.
+      #   `["bug.discover", "reference=BUG#1"]`
+      # @param program [String] the name the runner's help calls this command by
+      # @return [void]
+      # @raise [SystemExit] always
+      def cli_form(domain, argv, program)
+        runtime = Hecks.boot(domain, install_facade: false)
+        text, status = Facade::CliRunner.call(runtime: runtime, argv: argv, program: program)
+        status.zero? ? puts(text) : abort(text)
+        exit 0
+      end
+
+      # Says whether `arg` is a step list rather than a verb: stdin, inline JSON, or
+      # a file that exists.
+      #
+      # @param arg [String] the first argument after the domain
+      # @return [Boolean] true when `arg` is script-shaped
+      def script_shaped?(arg) = arg == "-" || arg.match?(/\A\s*\{/) || File.file?(arg)
+
+      # Reads the step list from stdin, from the argument itself, or from a file,
+      # decided by looking, because a script beginning with `{` is not a filename
+      # anybody meant.
+      #
+      # @param script [String] `-`, inline JSON, or a file path
+      # @return [String] the script's JSON text
+      # @raise [SystemExit] when `script` names no file
+      def read_source(script)
+        case script
+        when "-" then $stdin.read
+        when /\A\s*\{/ then script
+        else
+          File.exist?(script) ? File.read(script) : abort("no such script: #{script}")
+        end
+      end
+
+      # Parses the step list before anything boots, because booting opens a real
+      # store and a typo in the JSON should cost a sentence, not a connection.
+      #
+      # @param source [String] the script's JSON text
+      # @return [Hash{String => Object}] the parsed script
+      # @raise [SystemExit] when `source` is not JSON
+      def parse(source)
+        JSON.parse(source)
+      rescue JSON::ParserError => e
+        abort "that is not JSON: #{e.message.lines.first.strip}"
+      end
+
+      # Runs every step and gathers what the runtime holds afterwards.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param steps [Array<Hash{String => Object}>] the script's steps, each a
+      #   `"verb"` or a `"query"` with optional `"args"`
+      # @return [Hash{Symbol => Object}] `:instances`, `:events`, `:refusals`,
+      #   `:reactions`, `:sagas` and `:queries`, in the order they are printed
+      def execute(runtime, steps)
+        refusals = []
+        queries = []
+        steps.each { |step| run_step(runtime, step, refusals, queries) }
+
+        { instances: instances(runtime), events: events(runtime), refusals: refusals,
+          reactions: runtime.reactions, sagas: runtime.sagas, queries: queries }
+      end
+
+      # @api private
+      def run_step(runtime, step, refusals, queries)
+        args = (step["args"] || {}).transform_keys(&:to_sym)
+        if (question = step["query"])
+          queries << ask(runtime, question, args)
+          return
+        end
+
+        verb = step["verb"]
+        begin
+          runtime.dispatch_flat(verb, args)
+        rescue StandardError => e
+          refusals << { verb: verb, error: e.message.to_s }
+        end
+      end
+
+      # @api private
+      def ask(runtime, question, args)
+        { query: question, args: args, rows: runtime.query(question, **args) }
+      rescue StandardError => e
+        { query: question, args: args, error: e.message }
+      end
+
+      # @api private
+      def instances(runtime)
+        runtime.registry.bluebooks.each_with_object({}) do |(domain_name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            runtime.registry.repository(domain_name, aggregate).all.each do |record|
+              all["#{domain_name}::#{aggregate.name}##{record.id}"] = record.state
+            end
+          end
+        end
+      end
+
+      # @api private
+      def events(runtime)
+        runtime.events.map do |event|
+          { name: event.name, aggregate: event.aggregate, id: event.id, payload: event.payload }
+        end
+      end
+
+      # Checks the script's `"expectations"` against what the run produced.
+      #
+      # @param expectations [Hash{String => Object}] the script's `"event_names"`,
+      #   `"refusals"` and `"instances"` expectations; `{}` when it declares none
+      # @param report [Hash{Symbol => Object}] what `execute` answered
+      # @return [Array<String>] one message per unmet expectation; empty when every
+      #   one held
+      def unmet_expectations(expectations, report)
+        missing_events = Array(expectations["event_names"]) - report[:events].map { |event| event[:name] }
+        unmet = []
+        unmet << "matrix expected events missing: #{missing_events.join(', ')}" unless missing_events.empty?
+        unmet.concat(unmet_refusals(Array(expectations["refusals"]), report[:refusals]))
+        unmet.concat(unmet_instances(expectations["instances"] || {}, report[:instances]))
+      end
+
+      # @api private
+      def unmet_refusals(expected_refusals, refusals)
+        expected_refusals.filter_map do |expected|
+          verb = expected.fetch("verb")
+          matched = refusals.any? do |refusal|
+            refusal[:verb] == verb && refusal[:error].include?(expected.fetch("includes"))
+          end
+          next if matched
+
+          # A refusal that changed its words is a different story from one that never
+          # happened, so the actual errors are printed beside the wanted one.
+          said = refusals.select { |refusal| refusal[:verb] == verb }.map { |refusal| refusal[:error] }.uniq
+          "matrix expected refusal missing: #{expected}\n  " \
+            "#{verb} actually refused with: #{said.empty? ? '(nothing — every attempt was accepted)' : said.inspect}"
+        end
+      end
+
+      # @api private
+      def unmet_instances(expected_instances, instances)
+        expected_instances.flat_map do |key, fields|
+          actual = instances[key] || {}
+          fields.filter_map do |field, value|
+            next if actual[field.to_sym] == value
+
+            "matrix expected #{key}.#{field}=#{value.inspect}, got #{actual[field.to_sym].inspect}"
+          end
+        end
+      end
+    end
+  end
+end