hecks 5.0.0 → 7.0.0

data/lib/hecks/adapters/driving/usage_log.rb

@@ -0,0 +1,146 @@
+require "fileutils"
+require "json"
+require_relative "usage_cache"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Keeps a local record of the commands and queries a launcher runs, so the everyday list and
+      # the timing of a deprecation rest on what people type rather than on a guess.
+      #
+      # A run appends one JSON line to `usage.jsonl` in the directory `UsageCache` already uses:
+      # the name as typed, the name it resolved to, the exit status, the duration in milliseconds
+      # and the date. No arguments, values or paths are written. The record is on unless
+      # `HECKS_USAGE=off` is set or a `usage.off` marker sits in that directory. The first run that
+      # writes prints one line on standard error saying so, then leaves a `usage.noticed` marker.
+      # Writing never fails the command it records.
+      module UsageLog
+        # The file each run appends its line to.
+        FILE = "usage.jsonl".freeze
+        # The variable that turns the record off when set to `off`.
+        OPT_OUT_VARIABLE = "HECKS_USAGE".freeze
+        # The marker file that turns the record off.
+        OPT_OUT_MARKER = "usage.off".freeze
+        # The marker file that says the first-run notice has been printed.
+        NOTICE_MARKER = "usage.noticed".freeze
+        # The line printed once, on the first run that writes.
+        NOTICE = "hecks keeps a local record of the commands it runs in %s; set HECKS_USAGE=off to stop.".freeze
+        # The window `summary` counts when none is given, in days.
+        DEFAULT_WINDOW = 30
+        # Seconds in a day.
+        DAY = 24 * 60 * 60
+
+        module_function
+
+        # Appends the line for one run, unless the record is off.
+        #
+        # @param argv [Array<String>] the command line as typed
+        # @param resolved [String, nil] the name the runner resolved it to
+        # @param status [Integer] the exit status the run answered
+        # @param started [Float] the monotonic clock reading when the run began
+        # @return [void]
+        def record(argv:, resolved:, status:, started:)
+          return unless enabled?
+
+          FileUtils.mkdir_p(directory)
+          notice
+          append(line(argv, resolved, status, started))
+        rescue StandardError
+          nil
+        end
+
+        # @return [Boolean] whether a run is recorded
+        def enabled?
+          ENV[OPT_OUT_VARIABLE].to_s != "off" && !File.exist?(marker(OPT_OUT_MARKER))
+        end
+
+        # Prints the first-run line once, then leaves its marker.
+        def notice
+          return if File.exist?(marker(NOTICE_MARKER))
+
+          warn(format(NOTICE, path))
+          FileUtils.touch(marker(NOTICE_MARKER))
+        end
+
+        # The entry for one run.
+        #
+        # @return [Hash] the fields `record` writes
+        def line(argv, resolved, status, started)
+          { "typed" => typed(argv), "resolved" => resolved, "status" => status,
+            "ms" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
+            "date" => Time.now.utc.strftime("%Y-%m-%d") }
+        end
+
+        # The name the person typed: the first word that is not a flag, past a `query` word.
+        #
+        # @return [String, nil]
+        def typed(argv)
+          words = argv.reject { |word| word.start_with?("-") }
+          words.shift if CliRunner::QUERY_WORDS.include?(words.first)
+          words.first
+        end
+
+        # Writes one entry as a line of the file.
+        def append(entry)
+          File.open(path, "a") { |file| file.puts(JSON.generate(entry)) }
+        end
+
+        # The entries on file, oldest first. A line that does not parse is skipped.
+        #
+        # @return [Array<Hash>]
+        def entries
+          File.readlines(path).filter_map { |line| JSON.parse(line) }
+        rescue SystemCallError, JSON::ParserError
+          []
+        end
+
+        # Counts the runs in the window and names the known ones that did not run in it.
+        #
+        # @param known [Array<String>] every name the launcher answers to, as the projection names
+        #   them
+        # @param window [Integer] how many days back a run counts
+        # @return [String] the text `hecks usage` prints
+        def summary(known:, window: DEFAULT_WINDOW)
+          counts = counts_since(window)
+          unrun = known.sort - counts.keys
+          ["runs in the last #{window} days, most used first:", *tally_lines(counts),
+           "", "never run in that window:", *unrun.map { |name| "  #{name}" }].join("\n")
+        end
+
+        # How often each resolved name ran since the window opened.
+        #
+        # @return [Hash{String => Integer}]
+        def counts_since(window)
+          since = (Time.now.utc - (window * DAY)).strftime("%Y-%m-%d")
+          resolved_names(entries.select { |entry| entry["date"].to_s >= since })
+        end
+
+        # @return [Hash{String => Integer}] how many runs resolved to each name
+        def resolved_names(runs)
+          runs.map { |entry| entry["resolved"] }.compact.tally
+        end
+
+        # @return [Array<String>] one line per name that ran, most used first
+        def tally_lines(counts)
+          ranked = counts.sort_by { |name, count| [-count, name] }
+          ranked.map { |name, count| format("  %<count>4d  %<name>s", count: count, name: name) }
+        end
+
+        # @return [String] the file the record lives in
+        def path
+          File.join(directory, FILE)
+        end
+
+        # @return [String] the directory the record lives in: the usage cache's own
+        def directory
+          UsageCache.directory
+        end
+
+        # @return [String] a marker file in the directory
+        def marker(name)
+          File.join(directory, name)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/write_guard.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "context_line"
+require_relative "../driven/worktree_overlay"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Refuses a write from a linked worktree whose bluebook would store in Memory there while the
+      # main checkout stores it elsewhere. It asks the same overlay question the worktree warning
+      # asks (WorktreeOverlay.gap), and reads stores the way `hecks config` does, so the refusal
+      # and the warning cannot disagree about what is missing.
+      module WriteGuard
+        module_function
+
+        # @param directory [String] the checkout the command runs in
+        # @param bluebook [String, nil] the bluebook the command belongs to
+        # @param stores [#call] answers the store rows of a directory
+        # @return [String, nil] the refusal, or nil when the write may proceed
+        def refusal(directory, bluebook, stores: STORES)
+          return unless bluebook
+
+          main, files = WorktreeOverlay.gap(directory)
+          return if files.empty?
+
+          main_kind = kind_in(stores.call(main), bluebook)
+          return if main_kind == ContextLine::MEMORY || main_kind == kind_in(stores.call(directory), bluebook)
+
+          message(bluebook, main_kind, files)
+        end
+
+        # @param rows [Array<Array(String, String, String)>] store rows
+        # @param bluebook [String]
+        # @return [String] the kind of store the bluebook uses, Memory when it has none of its own
+        def kind_in(rows, bluebook)
+          row = rows.find { |label, _value, _source| label == "store #{bluebook}" }
+          ContextLine.kind(row ? row[1] : ContextLine::MEMORY)
+        end
+
+        # @return [String] the refusal naming the bluebook, the store and the missing files
+        def message(bluebook, main_kind, files)
+          "hecks: refused: #{bluebook} stores in #{main_kind} in the main checkout, and this worktree " \
+            "lacks #{files.join(", ")}, so the write would land in Memory here. " \
+            "Run the command from the main checkout."
+        end
+
+        # Answers the store rows of a directory, through the adapter `hecks config` uses.
+        STORES = lambda do |directory|
+          require_relative "../../hecks/adapters/settings_reading"
+          Hecks::Adapters::SettingsReading.new.stores(directory)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving.rb

@@ -10,7 +10,6 @@ module Hecks
   # A constant owned by user code or the stdlib is left alone with a warning.
   module Namespace
     # A live registry, mutated by `install`, so it cannot be frozen.
-    # rubocop:disable-next Style/MutableConstant
     GENERATED = {}
 
     module_function

data/lib/hecks/assembly.rb

@@ -0,0 +1,101 @@
+module Hecks
+  # Where a boot is put together: the one place that reads the process environment for a boot and
+  # plugs the Ruby driving adapter into the dispatcher the runtime hands back.
+  #
+  # The runtime (`Runtime::Loader`) only loads, checks and dispatches; it reads no environment
+  # variable and installs no adapter. Everything a boot takes from outside the domain arrives here.
+  #
+  # @example
+  #   Hecks::Assembly.boot("examples/pizzas/bluebook")
+  #     .dispatch("Pizzas::Pizza.CreatePizza", name: "Margherita")
+  module Assembly
+    # Default for a boot's `environment:` keyword: read `HECKS_ENVIRONMENT`. An explicit `nil`
+    # means no overlay, whatever the variable holds.
+    FROM_ENV = :from_env
+
+    module_function
+
+    # The overlay a boot loads: the caller's own choice (nil meaning none), else the
+    # `HECKS_ENVIRONMENT` variable when the caller left the keyword at its default. A domain with
+    # no `environments/<name>.*` files ignores either.
+    #
+    # @param environment [String, nil, Symbol] the overlay a caller passed, or `FROM_ENV`
+    # @return [String, nil] the overlay name; nil for none
+    def selected_environment(environment)
+      return environment unless environment == FROM_ENV
+
+      named = ENV["HECKS_ENVIRONMENT"].to_s.strip
+      named.empty? ? nil : named
+    end
+
+    # Boots a domain directory. See `Runtime::Loader.boot`.
+    #
+    # @param path [String] path to a domain directory, or a file inside one
+    # @param shared [String, nil] a shared-root override
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
+    # @param environment [String, nil, Symbol] the overlay, or `FROM_ENV` for `HECKS_ENVIRONMENT`
+    # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted dispatcher
+    def boot(path, shared: nil, install_driving: true, environment: FROM_ENV)
+      drive(Runtime::Loader.boot(path, shared: shared, environment: selected_environment(environment)),
+            install_driving)
+    end
+
+    # Loads a domain's declarations without binding any adapter. See `Runtime::Loader.describe`.
+    #
+    # @param path [String] path to a domain directory, or a file inside one
+    # @param shared [String, nil] a shared-root override
+    # @param environment [String, nil, Symbol] the overlay, or `FROM_ENV` for `HECKS_ENVIRONMENT`
+    # @return [Runtime::Loader::Described] the loaded registry, answering `registry`
+    def describe(path, shared: nil, environment: FROM_ENV)
+      Runtime::Loader.describe(path, shared: shared, environment: selected_environment(environment))
+    end
+
+    # Finishes a boot from declarations `describe` already loaded. See
+    # `Runtime::Loader.boot_described`.
+    #
+    # @param described [Runtime::Loader::Described] what `describe` answered
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
+    # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted dispatcher
+    def boot_described(described, install_driving: true)
+      drive(Runtime::Loader.boot_described(described), install_driving)
+    end
+
+    # Boots exactly the named files. See `Runtime::Loader.boot_files`.
+    #
+    # @param paths [String, Array<String>] one or more file paths within the domain
+    # @param shared [String, nil] a shared-root override
+    # @param install_driving [Boolean] install the `Widget::Item.Add`-style facade
+    # @param environment [String, nil, Symbol] the overlay, or `FROM_ENV` for `HECKS_ENVIRONMENT`
+    # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted dispatcher
+    def boot_files(paths, shared: nil, install_driving: true, environment: FROM_ENV)
+      drive(Runtime::Loader.boot_files(paths, shared: shared, environment: selected_environment(environment)),
+            install_driving)
+    end
+
+    # Installs the Ruby driving adapter (`Widget::Item.Add(...)`) closed over `dispatcher`.
+    #
+    # @param dispatcher [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] a booted
+    #   dispatcher
+    # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the same dispatcher
+    def bind_runtime(dispatcher)
+      Adapters::Driving::Ruby.install(dispatcher)
+      dispatcher
+    end
+
+    # Installs the Ruby driving adapter only for a domain that declares ports. An adapter behind a
+    # port reaches its domain through those constants, so a run that boots without them (a verb
+    # run, an outbox redrive) would have the adapter refused with `uninitialized constant`; a
+    # domain with no port keeps the cheaper boot.
+    #
+    # @param dispatcher [Runtime::Dispatcher] a booted dispatcher
+    # @return [Runtime::Dispatcher] the same dispatcher
+    def bind_ported_runtime(dispatcher)
+      registry = dispatcher.registry
+      registry.ports.any? ? bind_runtime(dispatcher) : dispatcher
+    end
+
+    # The dispatcher, with the Ruby driving adapter installed over it when asked.
+    def drive(dispatcher, install_driving) = install_driving ? bind_runtime(dispatcher) : dispatcher
+    private_class_method :drive
+  end
+end

data/lib/hecks/behaviors/dsl.rb

@@ -1,4 +1,5 @@
 require_relative "ir"
+require_relative "../module_folders"
 
 # The authoring surface for `Hecks.behaviors "Name" do ... end`, built with `instance_eval`.
 module Hecks
@@ -17,6 +18,7 @@ module Hecks
         @setups        = []
         @input         = {}
         @expect        = {}
+        @role          = nil
       end
 
       # Records which command or query this test exercises.
@@ -35,12 +37,21 @@ module Hecks
       # Records one setup command to dispatch before the test itself runs.
       #
       # @param command [String, Symbol] the setup command's verb
+      # @param as [String, nil] the role the dispatch runs as; unchecked when nil, as a
+      #   command's `role` only binds a caller that states one
       # @param kwargs [Hash{Symbol => Object}] the setup command's own arguments
       # @return [void]
-      def setup(command, **kwargs)
-        @setups << TestSetup.new(command: command, args: kwargs)
+      def setup(command, as: nil, **kwargs)
+        @setups << TestSetup.new(command: command, args: kwargs, role: as)
       end
 
+      # Runs the tested command as a caller holding `role`, so the command's own `role` is
+      # checked against it.
+      #
+      # @param role [String] the role the tested dispatch runs as
+      # @return [String] `role`
+      def as(role) = @role = role
+
       # Merges fields into the arguments the tested command or query is called with.
       #
       # @param kwargs [Hash{Symbol => Object}] argument names and values to merge in
@@ -69,7 +80,7 @@ module Hecks
 
         TestCase.new(description: @description, tests_command: @tests_command,
                      on_aggregate: @on_aggregate, kind: @kind,
-                     setups: @setups, input: @input, expect: @expect)
+                     setups: @setups, input: @input, expect: @expect, role: @role)
       end
 
       private
@@ -122,9 +133,12 @@ module Hecks
       #
       # @param paths [Array<String>] paths to the files this suite's domain boots
       #   from, relative to the `.behaviors` file
+      # @param modules [Symbol, nil] `:all` adds the bluebook of every module folder beside the
+      #   `.behaviors` file (see ModuleFolders)
       # @return [void]
-      def loads(*paths)
+      def loads(*paths, modules: nil)
         @loads = paths.map { |path| File.expand_path(path, @source_dir) }
+        @loads.concat(ModuleFolders.bluebooks(@source_dir)) if modules == :all
       end
 
       # Builds and records one test case.

data/lib/hecks/behaviors/expectations/boot.rb

@@ -12,7 +12,6 @@ module Hecks
         # Cached per suite, keyed by `loads`' file paths and mtimes, so a boot is
         # reused across tests but an edited bluebook boots fresh on the next one.
         # Mutated in place (`RUNTIMES[key] ||= boot_and_guard(files)`).
-        # rubocop:disable-next Style/MutableConstant
         RUNTIMES      = {}
         RUNTIMES_LOCK = Mutex.new
         private_constant :RUNTIMES, :RUNTIMES_LOCK
@@ -21,7 +20,7 @@ module Hecks
         #
         # @param suite [Behaviors::BehaviorsSuite] the suite whose `loads` files boot
         #   the runtime
-        # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the cached or
+        # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the cached or
         #   freshly booted, Memory-only-guarded runtime
         # @raise [Malformed] if any aggregate the suite boots is not bound to the
         #   default (Memory) adapter
@@ -39,11 +38,11 @@ module Hecks
         #
         # @param files [Array<String>] absolute paths to the bluebook/hecksagon/world
         #   files to boot
-        # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted,
+        # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted,
         #   Memory-only-guarded runtime
         # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
         def boot_and_guard(files)
-          runtime = Hecks::Runtime::Loader.boot_files(files, install_driving: false)
+          runtime = Hecks.boot_files(files, install_driving: false)
           guard_memory_only!(runtime)
           runtime
         end
@@ -51,14 +50,15 @@ module Hecks
         # Refuses a runtime where any aggregate is bound to anything other than the
         # default (Memory) adapter, so tests can never leak state or touch a real store.
         #
-        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+        # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted
         #   runtime to check
         # @return [void]
         # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
         def guard_memory_only!(runtime)
-          runtime.registry.bluebooks.each_value do |bluebook|
+          registry = runtime.registry
+          registry.bluebooks.each_value do |bluebook|
             bluebook.aggregates.each do |aggregate|
-              bind = Ports::Persistence::BindingPolicy.resolve(runtime.registry, bluebook.name, aggregate)
+              bind = Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, aggregate)
               next if bind.adapter == Ports::Persistence::DEFAULT_ADAPTER
 
               raise Malformed, non_memory_message(bluebook, aggregate, bind)

data/lib/hecks/behaviors/expectations/checks.rb

@@ -50,7 +50,7 @@ module Hecks
           expected = test.expect[:emits]
           return unless expected
 
-          actual = runtime.registry.event_log[before..].map(&:name)
+          actual = runtime.events[before..].map(&:name)
           return if actual == expected
 
           fail_result(test, "expected emits: #{expected.inspect}, got #{actual.inspect}")

data/lib/hecks/behaviors/expectations/dispatching.rb

@@ -9,10 +9,10 @@ module Hecks
         # Reads the aggregate back from the repository, not `Result#state` — a
         # policy's own reentrant dispatch can re-save the record afterward.
         #
-        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+        # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the suite's
         #   booted runtime
         # @param verb [String] the dispatched command's dotted FQN
-        # @param result [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result]
+        # @param result [Runtime::Dispatcher::Result, Adapters::Lambda::RemoteDispatcher::Result]
         #   the dispatch's own result
         # @return [Hash{Symbol => Object}] the settled record's current state, read
         #   back from the repository; `result.state` (or `{}`) when the result has no
@@ -28,24 +28,25 @@ module Hecks
           return unless result.respond_to?(:id) && result.id
 
           aggregate = verb_aggregate(runtime, verb)
-          aggregate && runtime.registry.repository(verb.split("::", 2).first, aggregate).find(result.id)
+          aggregate && runtime.repository(verb.split("::", 2).first, aggregate).find(result.id)
         end
 
         # @return [Bluebook::Aggregate, nil] the aggregate a dotted verb names, when it is declared
         def verb_aggregate(runtime, verb)
           domain, rest = verb.split("::", 2)
           aggregate_name = rest.to_s.split(".", 2).first
-          runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+          runtime.bluebook(domain)&.aggregate(aggregate_name)
         end
 
         # Splits a mixed dispatch (receiver identity plus declared facts, e.g.
         # `to: { file: 2, rank: 2 }`) into the dispatcher's strict `to:`/`with:` envelope.
         #
-        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's booted runtime
+        # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the suite's
+        #   booted runtime
         # @param verb [String] the command's dotted FQN, or a port operation's
         # @param args [Hash{Symbol => Object}] the facts, mixing identity and declared arguments
-        # @return [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the dispatch
-        #   result
+        # @return [Runtime::Dispatcher::Result, Adapters::Lambda::RemoteDispatcher::Result] the
+        #   dispatch result
         # @raise [Runtime::UnknownVerb] if `verb` names an undeclared construct
         # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class, when the domain refuses
         def dispatch_command(runtime, verb, args)
@@ -73,7 +74,7 @@ module Hecks
         # The same "Head.Rest" split `Dispatcher#dispatch` already uses — just a
         # domain/aggregate and port-name lookup, no command resolution needed.
         #
-        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+        # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the suite's
         #   booted runtime
         # @param verb [String] the verb to check, dotted FQN shaped
         # @return [Boolean] true if `verb` names a port operation on a declared aggregate
@@ -81,7 +82,7 @@ module Hecks
           domain, aggregate_name, command_path = Naming.split_verb(verb)
           return false unless command_path
 
-          aggregate = runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+          aggregate = runtime.bluebook(domain)&.aggregate(aggregate_name)
           return false unless aggregate
 
           head, rest = command_path.split(".", 2)

data/lib/hecks/behaviors/expectations/qualify.rb

@@ -10,7 +10,7 @@ module Hecks
         # @param command [String, Symbol] a bare verb, or an already-dotted FQN
         # @param on_aggregate [String, Symbol, nil] the aggregate to search, or nil to
         #   search every aggregate of every bluebook
-        # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted
+        # @param bluebooks [Array<Bluebook::Declaration>] every bluebook the suite booted
         # @param kind [Symbol] `:command` or `:query`
         # @return [String] `command` unchanged if already dotted, otherwise its resolved
         #   dotted FQN
@@ -28,18 +28,18 @@ module Hecks
         # @param command [String, Symbol] the bare verb to search for
         # @param on_aggregate [String, Symbol, nil] the aggregate to search, or nil to
         #   search every aggregate of every bluebook
-        # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted
+        # @param bluebooks [Array<Bluebook::Declaration>] every bluebook the suite booted
         # @param kind [Symbol] `:command` or `:query`
-        # @return [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] every matching
-        #   (chapter, aggregate) pair
+        # @return [Array<Array(Bluebook::Declaration, Bluebook::Aggregate)>] every matching
+        #   (bluebook, aggregate) pair
         def qualify_candidates(command, on_aggregate, bluebooks, kind)
           members = kind == :query ? :queries : :commands
           aggregate_pairs(bluebooks, on_aggregate)
             .select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
         end
 
-        # @return [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] the named aggregate of
-        #   each chapter that has it, or every aggregate of every chapter when none is named
+        # @return [Array<Array(Bluebook::Declaration, Bluebook::Aggregate)>] the named aggregate of
+        #   each bluebook that has it, or every aggregate of every bluebook when none is named
         def aggregate_pairs(bluebooks, on_aggregate)
           return bluebooks.flat_map { |bb| bb.aggregates.map { |agg| [bb, agg] } } unless on_aggregate
 
@@ -49,11 +49,11 @@ module Hecks
         # Resolves a search's candidates to exactly one dotted FQN; zero or more
         # than one both refuse, each with a different message.
         #
-        # @param candidates [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] the
-        #   matching (chapter, aggregate) pairs found by `qualify_candidates`
+        # @param candidates [Array<Array(Bluebook::Declaration, Bluebook::Aggregate)>] the
+        #   matching (bluebook, aggregate) pairs found by `qualify_candidates`
         # @param command [String, Symbol] the bare verb that was searched for
         # @param kind [Symbol] `:command` or `:query`, for the refusal message
-        # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted,
+        # @param bluebooks [Array<Bluebook::Declaration>] every bluebook the suite booted,
         #   for the refusal message
         # @return [String] the one candidate's dotted FQN
         # @raise [ArgumentError] if `candidates` is empty, or holds more than one

data/lib/hecks/behaviors/expectations.rb

@@ -1,5 +1,6 @@
 require_relative "ir"
 require_relative "../runtime/loader"
+require_relative "../runtime/caller"
 require_relative "../runtime/errors"
 require_relative "../runtime/value"
 require_relative "../runtime/reaction_invocation"
@@ -36,14 +37,15 @@ module Hecks
       #
       # @param test [Behaviors::TestCase] the test case to run
       # @param suite [Behaviors::BehaviorsSuite] the suite `test` belongs to
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher, nil] an
+      # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher, nil] an
       #   already-booted runtime to reuse and reset; nil boots (or reuses the cached
       #   boot of) `suite.loads` via `runtime_for`
       # @return [Result] the test's pass, fail, or error outcome
       def run_one(test, suite, runtime: nil)
         runtime ||= runtime_for(suite)
-        runtime.registry.reset_runtime_state!
-        bluebooks = runtime.registry.bluebooks.values
+        registry = runtime.registry
+        registry.reset_runtime_state!
+        bluebooks = registry.bluebooks.values
         replay_setup(test, runtime, bluebooks) || run_tested(test, runtime, bluebooks)
       rescue StandardError => e
         error_result(test, "#{e.class}: #{e.message}")
@@ -59,20 +61,32 @@ module Hecks
         current_setup = nil
         test.setups.each do |setup|
           current_setup = setup
-          dispatch_command(runtime, qualify(setup.command, nil, bluebooks, kind: :command), setup.args)
+          verb = qualify(setup.command, nil, bluebooks, kind: :command)
+          as_role(setup.role) { dispatch_command(runtime, verb, setup.args) }
         end
         nil
       rescue *REFUSAL_CLASSES => e
         error_result(test, "setup #{current_setup&.command.inspect} refused: #{e.message}")
       end
 
+      # Runs the block as a caller holding `role`, or with no caller bound when there is none.
+      #
+      # @param role [String, nil] the role the dispatch runs as
+      # @yield the dispatch
+      # @return [Object] the block's result
+      def as_role(role, &)
+        return yield unless role
+
+        Hecks::Runtime::Caller.as(role: role, &)
+      end
+
       # Qualifies and dispatches (or queries) the command under test, catching a
       # domain refusal as the test's own outcome rather than an error.
       #
       # @param test [Behaviors::TestCase] the test case to run
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the suite's
       #   booted runtime
-      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted,
+      # @param bluebooks [Array<Bluebook::Declaration>] every bluebook the suite booted,
       #   searched to qualify a bare command/query name
       # @return [Result] the test's pass, fail, or error outcome
       def run_tested(test, runtime, bluebooks)
@@ -90,13 +104,13 @@ module Hecks
       # Dispatches the command under test and checks its `expect`.
       #
       # @param test [Behaviors::TestCase] the test case to run
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the suite's
       #   booted runtime
       # @param verb [String] the command's dotted FQN
       # @return [Result] the test's pass or fail outcome
       def run_command(test, runtime, verb)
-        before = runtime.registry.event_log.length
-        result = dispatch_command(runtime, verb, test.input)
+        before = runtime.events.length
+        result = as_role(test.role) { dispatch_command(runtime, verb, test.input) }
         failure = refused_but_succeeded(test, "dispatch") || unexpected_emits(test, runtime, before)
         return failure if failure
 
@@ -106,7 +120,7 @@ module Hecks
       # Runs the query under test and checks its `expect`.
       #
       # @param test [Behaviors::TestCase] the test case to run
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the suite's
       #   booted runtime
       # @param verb [String] the query's dotted FQN
       # @return [Result] the test's pass or fail outcome

data/lib/hecks/behaviors/ir.rb

@@ -5,10 +5,12 @@
 module Hecks
   # The `.behaviors` toolkit: DSL, IR, runner and rspec shim.
   module Behaviors
-    TestSetup = Struct.new(:command, :args, keyword_init: true)
+    # One setup dispatch; `role`, when given, is the role the dispatch runs as.
+    TestSetup = Struct.new(:command, :args, :role, keyword_init: true)
 
+    # One test; `role`, when given, is the role the tested dispatch runs as.
     TestCase = Struct.new(:description, :tests_command, :on_aggregate, :kind,
-                          :setups, :input, :expect, keyword_init: true) do
+                          :setups, :input, :expect, :role, keyword_init: true) do
       # Whether `tests_command` is already a fully qualified verb name.
       #
       # @return [Boolean] true when `tests_command` contains a `.`

data/lib/hecks/behaviors/rspec.rb

@@ -28,7 +28,7 @@ module Hecks
         return proc { it("loads without a parse error") { raise parsed.parse_error } } if parsed.parse_error
 
         proc do
-          parsed.suite.tests.each do |test|
+          parsed.tests.each do |test|
             it(test.description) do
               run = Expectations.run_one(test, parsed.suite)
               raise run.message if run.status != :pass