hecks 5.0.0 → 6.0.0

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

@@ -1,5 +1,5 @@
-require_relative "../../chapters"
-require_relative "ruby/chapter"
+require_relative "../../framework_bluebooks"
+require_relative "ruby/declaration"
 require_relative "ruby/aggregate_module"
 
 module Hecks
@@ -14,59 +14,60 @@ module Hecks
         # Names that would shadow the machinery a Handle runs on; a field with one gets no reader.
         RESERVED = %i[id state events reload inspect to_h hash class].freeze
 
-        extend Chapter
+        extend Declaration
         extend AggregateModule
 
         module_function
 
-        # Installs one top-level module per booted chapter, and one per aggregate, each
+        # Installs one top-level module per booted bluebook, and one per aggregate, each
         # closing over `dispatcher`, so `Pizzas::Pizza` and the bare `Pizza` both open the
         # module of the boot that ran last.
         #
-        # A gem chapter a hecksagon `attaches` installs nothing (`Query`, `Port` stay free).
-        # An aggregate sharing its chapter's name gets no second constant. A name that user
+        # A gem bluebook a hecksagon `attaches` installs nothing (`Query`, `Port` stay free).
+        # An aggregate sharing its bluebook's name gets no second constant. A name that user
         # code or the stdlib already owns is left alone with a warning (see `Namespace.install`).
         #
-        # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+        # @param dispatcher [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted
         #   dispatcher every installed module dispatches and queries through
-        # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the same `dispatcher`
-        # @raise [NameError] if a chapter or aggregate name is not a valid constant name
+        # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the same `dispatcher`
+        # @raise [NameError] if a bluebook or aggregate name is not a valid constant name
         def install(dispatcher)
-          Admission.admit!(dispatcher.registry, "Ruby")
-          dispatcher.registry.bluebooks.each_value do |bluebook|
-            install_chapter(dispatcher, bluebook) unless attached_chapter?(dispatcher.registry, bluebook)
+          registry = dispatcher.registry
+          Admission.admit!(registry, "Ruby")
+          registry.bluebooks.each_value do |bluebook|
+            install_bluebook(dispatcher, bluebook) unless attached_bluebook?(registry, bluebook)
           end
           dispatcher
         end
 
-        # Installs one chapter's module, and the top-level shortcut of each of its aggregates.
-        def install_chapter(dispatcher, bluebook)
-          chapter = chapter_module(dispatcher, bluebook)
-          Namespace.install(*placement(bluebook), chapter)
-          # A namespaced chapter keeps its aggregates inside its namespace: top-level
+        # Installs one bluebook's module, and the top-level shortcut of each of its aggregates.
+        def install_bluebook(dispatcher, bluebook)
+          declaration = bluebook_module(dispatcher, bluebook)
+          Namespace.install(*placement(bluebook), declaration)
+          # A namespaced bluebook keeps its aggregates inside its namespace: top-level
           # shortcuts would bring back the collisions the namespace exists to avoid.
           return if bluebook.namespace
 
           bluebook.aggregates.each do |aggregate|
             next if aggregate.hecks_name == bluebook.name
 
-            Namespace.install(Object, aggregate.hecks_name, chapter.const_get(aggregate.hecks_name, false))
+            Namespace.install(Object, aggregate.hecks_name, declaration.const_get(aggregate.hecks_name, false))
           end
         end
 
-        # Whether `bluebook` is a gem chapter that a hecksagon attached rather than a domain's own.
+        # Whether `bluebook` is a gem bluebook that a hecksagon attached rather than a domain's own.
         #
         # @param registry [Runtime::Registry] the booted registry
-        # @param bluebook [Bluebook::Chapter] the chapter under test
+        # @param bluebook [Bluebook::Declaration] the bluebook under test
         # @return [Boolean]
-        def attached_chapter?(registry, bluebook)
-          registry.bounded?(bluebook.name) && Hecks::Chapters.index.key?(bluebook.name)
+        def attached_bluebook?(registry, bluebook)
+          registry.bounded?(bluebook.name) && Hecks::FrameworkBluebooks.index.key?(bluebook.name)
         end
 
-        # Where a chapter's module installs: `Object::<name>`, or the constant path its
+        # Where a bluebook's module installs: `Object::<name>`, or the constant path its
         # `namespace` names, creating any missing parent modules along the way.
         #
-        # @param bluebook [Bluebook::Chapter] the chapter being installed
+        # @param bluebook [Bluebook::Declaration] the bluebook being installed
         # @return [Array(Module, String)] the parent module and the constant name within it
         def placement(bluebook)
           return [Object, bluebook.name] unless bluebook.namespace

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

@@ -1,6 +1,7 @@
 require "digest"
 require "fileutils"
 require "json"
+require_relative "../../switches"
 
 module Hecks
   module Adapters
@@ -11,12 +12,12 @@ module Hecks
       # and reading those is most of what a launcher costs. The answer is kept in a file named for a
       # digest of everything it depends on (the domain's declaration files, the gem's judging code
       # and adapters, the hecks and Ruby versions, the environment overlay, the command line and
-      # the program name),
-      # so any edit to one of them is simply a different entry: nothing is ever stale, only unused.
+      # the program name), so any edit to one is a different entry: nothing is stale, only unused.
       # Only an answer that ended well is kept, and any trouble with the cache itself is ignored
       # and the help is worked out as if it did not exist.
       #
-      # `HECKS_NO_USAGE_CACHE=1` turns it off; `HECKS_CACHE_DIR` moves it.
+      # `hecks test_suite_run.clear_caches!` empties it; `HECKS_NO_USAGE_CACHE=1` turns it off for a
+      # test process; `HECKS_CACHE_DIR` moves it.
       module UsageCache
         # The variable that turns the cache off when set to anything but empty or `0`.
         DISABLE_VARIABLE = "HECKS_NO_USAGE_CACHE".freeze
@@ -65,6 +66,16 @@ module Hecks
           off.empty? || off == "0"
         end
 
+        # Deletes every remembered help text, which `HECKS_NO_USAGE_CACHE` skips. The
+        # directory is shared with other cache files, so only this cache's entries go.
+        #
+        # @return [Boolean] whether any entry was removed
+        def clear
+          Dir.glob(File.join(directory, "usage-*.json")).each { |entry| File.delete(entry) }.any?
+        rescue SystemCallError
+          false
+        end
+
         # @return [String] the directory entries live in
         def directory
           ENV[DIRECTORY_VARIABLE] || File.join(ENV["XDG_CACHE_HOME"] || File.join(Dir.home, ".cache"), "hecks")

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

@@ -17,6 +17,7 @@ module Hecks
         @setups        = []
         @input         = {}
         @expect        = {}
+        @role          = nil
       end
 
       # Records which command or query this test exercises.
@@ -35,12 +36,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 +79,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

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

@@ -21,7 +21,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 +39,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 +51,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

data/lib/hecks/behaviors/runner.rb

@@ -1,4 +1,5 @@
 require_relative "expectations"
+require_relative "../sentence_form"
 
 # Hecks::Behaviors.run(path) / .run_all(dir)
 #
@@ -8,10 +9,16 @@ module Hecks
   module Behaviors
     FileResult = Struct.new(:path, :parse_error, :runs, keyword_init: true)
     SweepResult = Struct.new(:root, :files_swept, :files, :summary, keyword_init: true)
-    ParseResult = Struct.new(:path, :suite, :parse_error, keyword_init: true)
+    ParseResult = Struct.new(:path, :suite, :parse_error, keyword_init: true) do
+      # @return [Array<Behaviors::TestCase>] the parsed suite's tests
+      def tests = suite.tests
+    end
 
     class LoadOutsideRunner < StandardError; end
 
+    # The last name of a namespaced class: `Hecks::SentenceForm::Refused` -> `Refused`.
+    LAST_CONSTANT = /\w+\z/
+
     class << self
       # The `.behaviors` file being `Kernel.load`ed; `Hecks.behaviors` reads it to resolve
       # `loads` and to refuse a file loaded any other way.
@@ -29,7 +36,10 @@ module Hecks
       #   a raised exception, or the file loading without calling `Hecks.behaviors`
       def parse(path)
         path = File.expand_path(path)
-        error = load_behaviors(path)
+        runnable = runnable(path)
+        return ParseResult.new(path: path, suite: nil, parse_error: runnable.fetch(:error)) if runnable.is_a?(Hash)
+
+        error = load_behaviors(runnable)
         return ParseResult.new(path: path, suite: nil, parse_error: error) if error
 
         suite = last_suite
@@ -48,7 +58,7 @@ module Hecks
         parsed = parse(path)
         return FileResult.new(path: parsed.path, parse_error: parsed.parse_error, runs: []) if parsed.parse_error
 
-        runs = parsed.suite.tests.map { |test| Expectations.run_one(test, parsed.suite) }
+        runs = parsed.tests.map { |test| Expectations.run_one(test, parsed.suite) }
         FileResult.new(path: parsed.path, parse_error: nil, runs: runs)
       end
 
@@ -59,7 +69,8 @@ module Hecks
       # @return [Behaviors::SweepResult] `files_swept` the count found, `files` one
       #   `FileResult` per file, and `summary` the aggregate counts `summarize` returns
       def run_all(dir)
-        files = Dir.glob(File.join(dir, "**", "*.behaviors"))
+        files = Dir.glob([File.join(dir, "**", "*.behaviors"),
+                          File.join(dir, "**", "*#{SentenceForm::EXAMPLES_EXTENSION}")])
         results = files.map { |path| run(path) }
         SweepResult.new(root: dir, files_swept: files.size, files: results, summary: summarize(results))
       end
@@ -84,6 +95,22 @@ module Hecks
 
       private
 
+      # The `.behaviors` file to load for `path`: the file itself, or for an examples file the
+      # `.behaviors` text compiled from it.
+      #
+      # @param path [String] an absolute `.behaviors` or examples file path
+      # @return [String, Hash{Symbol => String}] the `.behaviors` file's path, or `{error:}`
+      #   naming why the examples could not be compiled
+      def runnable(path)
+        SentenceForm.examples?(path) ? SentenceForm.write_behaviors(path) : path
+      rescue SentenceForm::Refused, SentenceForm::ParserMissing => e
+        { error: "#{refusal_name(e)}: #{e.message}" }
+      end
+
+      # @param error [Exception] a refusal raised while compiling examples
+      # @return [String] the error's class name without its namespace
+      def refusal_name(error) = error.class.name[LAST_CONSTANT]
+
       # `Kernel.load`s the file with `loading_path` pointing at it.
       #
       # @param path [String] the `.behaviors` file's absolute path