hecks 4.0.0 → 6.0.0

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

@@ -3,13 +3,14 @@ require "stringio"
 require_relative "../../ports/identity_generation"
 require_relative "../../runtime/errors"
 require_relative "cli"
+require_relative "../../text"
 
 module Hecks
   module Adapters
     module Driving
       # What a domain's world file adds to its generated launcher, all of it opt-in.
       #
-      # A `.world` that declares a `launcher` setting switches these on for that chapter; a
+      # A `.world` that declares a `launcher` setting switches these on for that bluebook; a
       # domain without one keeps the launcher's plain forms exactly:
       #
       # - **run_keys** mints the `run` key of a creating command that was given none.
@@ -18,12 +19,16 @@ module Hecks
       # - **report** lists the settled commands whose answer is the report they recorded, as text.
       # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
       # - **streams** lists the questions `--stream` may tail, one JSON line per new entry.
-      # - **maintainer**, **chapters**, **maintainer_chapters** shape the help for its audience.
+      # - **maintainer**, **bluebooks**, **maintainer_bluebooks** shape the help for its audience.
       module LauncherOptions
         SETTING = "launcher".freeze
         WAIT    = "--wait".freeze
         STREAM  = "--stream".freeze
         RUN_KEY = "run.value".freeze
+        # The dots and colons between a question's bluebook, aggregate and own name.
+        NAME_SEPARATORS = /[.:]+/
+        # A `GAP (n)` report heading whose count is above zero.
+        NONZERO_GAP_HEADING = /^GAP \((?!0\))\d+\)/
         # The lifecycle mark naming the states `--wait` reports as a failure (exit 1); the lifecycle
         # says so with `mark :failure, "flagged"` (ADR 0097), so no setting lists them.
         FAILURE_MARK = "failure".freeze
@@ -35,22 +40,22 @@ module Hecks
 
         module_function
 
-        # Reads a chapter's `launcher` setting.
+        # Reads a bluebook's `launcher` setting.
         #
-        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-        # @param chapter [String] the chapter the command line speaks to
-        # @return [Hash{Symbol => Object}, nil] the setting, or nil when the chapter did not opt in
-        def settings(runtime, chapter)
+        # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted domain
+        # @param bluebook [String] the bluebook the command line speaks to
+        # @return [Hash{Symbol => Object}, nil] the setting, or nil when the bluebook did not opt in
+        def settings(runtime, declaration)
           return unless runtime.respond_to?(:registry)
 
-          found = runtime.registry.world(chapter)&.for_verb(SETTING)
+          found = runtime.world(declaration)&.for_verb(SETTING)
           found.nil? || found.empty? ? nil : found
         end
 
-        # The options the launcher's projection is asked for: the program's name, the chapter's
+        # The options the launcher's projection is asked for: the program's name, the bluebook's
         # launcher names, and whether run keys are minted (so help shows them optional).
         #
-        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @param settings [Hash, nil] the bluebook's `launcher` setting
         # @param program [String] how the caller was invoked
         # @return [Hash{Symbol => Object}] the options `Projector::CliProjector` reads
         def projection(settings, program)
@@ -73,24 +78,24 @@ module Hecks
         end
 
         # The help options one audience gets: the aggregates left out of the lists (`maintainer`,
-        # shown only in a hecks checkout or to `--maintainer`) and the chapters pointed at
-        # (`chapters`, plus `maintainer_chapters` in a checkout). A chapter that did not opt in
+        # shown only in a hecks checkout or to `--maintainer`) and the bluebooks pointed at
+        # (`bluebooks`, plus `maintainer_bluebooks` in a checkout). A bluebook that did not opt in
         # gets neither.
         #
-        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @param settings [Hash, nil] the bluebook's `launcher` setting
         # @param maintainer [Boolean] whether the help is for someone working on a hecks checkout
-        # @return [Hash{Symbol => Object}] `:hide` and `:chapters`, to merge into the projection
+        # @return [Hash{Symbol => Object}] `:hide` and `:bluebooks`, to merge into the projection
         def audience(settings, maintainer)
           return {} unless settings
 
-          chapters = Array(settings[:chapters]) + (maintainer ? Array(settings[:maintainer_chapters]) : [])
-          { hide: maintainer ? [] : Array(settings[:maintainer]).map(&:to_s), chapters: chapters.map(&:to_s) }
+          named = Array(settings[:bluebooks]) + (maintainer ? Array(settings[:maintainer_bluebooks]) : [])
+          { hide: maintainer ? [] : Array(settings[:maintainer]).map(&:to_s), declarations: named.map(&:to_s) }
         end
 
         # Runs the block with standard error held back, so the wiring notes hecks prints about its
-        # own
-        # chapters (a Memory journal loses sagas on restart) do not open a console session. They are
-        # for an operator running a stored journal. A raised error still surfaces, unchanged.
+        # own bluebooks (a Memory journal loses sagas on restart) do not open a console session.
+        # They are for an operator running a stored journal. A raised error still surfaces,
+        # unchanged.
         #
         # @param hold [Boolean] whether to hold standard error back; false runs the block as it is
         # @yield the boot
@@ -142,7 +147,7 @@ module Hecks
 
         # Whether a command always waits for its reactions, as if `--wait` had been given.
         #
-        # @param launcher [Hash, nil] the chapter's `launcher` setting
+        # @param launcher [Hash, nil] the bluebook's `launcher` setting
         # @param spec [Hash] the command's projected spec
         # @return [Boolean] true for a command the setting lists under `settled`
         def settled?(launcher, spec)
@@ -154,7 +159,7 @@ module Hecks
         # Whether a question about one run refuses a run this process does not hold, instead of
         # answering an empty list.
         #
-        # @param launcher [Hash, nil] the chapter's `launcher` setting
+        # @param launcher [Hash, nil] the bluebook's `launcher` setting
         # @param spec [Hash] the question's projected spec
         # @return [Boolean] true for a question the setting lists under `unknown_runs`
         def unknown_run?(launcher, spec)
@@ -165,7 +170,7 @@ module Hecks
 
         # Whether a command prints the report it recorded instead of its whole record.
         #
-        # @param launcher [Hash, nil] the chapter's `launcher` setting
+        # @param launcher [Hash, nil] the bluebook's `launcher` setting
         # @param spec [Hash] the command's projected spec
         # @return [Boolean] true for a command the setting lists under `report`
         def report?(launcher, spec)
@@ -174,17 +179,17 @@ module Hecks
           Array(launcher[:report]).map(&:to_s).include?(spec[:short].to_s)
         end
 
-        # Whether a question may be tailed with `--stream`: the chapter's `launcher` setting lists
+        # Whether a question may be tailed with `--stream`: the bluebook's `launcher` setting lists
         # it
         # under `streams`, by the question's own name.
         #
-        # @param launcher [Hash, nil] the chapter's `launcher` setting
+        # @param launcher [Hash, nil] the bluebook's `launcher` setting
         # @param spec [Hash] the question's projected spec
         # @return [Boolean] true for a question the setting names
         def streams?(launcher, spec)
           return false unless launcher && spec[:kind] == :query
 
-          Array(launcher[:streams]).map(&:to_s).include?(spec[:command].to_s.split(/[.:]+/).last)
+          Array(launcher[:streams]).map(&:to_s).include?(spec[:command].to_s.split(NAME_SEPARATORS).last)
         end
 
         # Takes `--stream` out of a question's words.
@@ -215,7 +220,7 @@ module Hecks
         # @param text [String, nil] the question's text answer
         # @return [Boolean] whether a `GAP (n)` heading with n above zero is in the text
         def gap_reported?(text)
-          text.is_a?(String) && text.match?(/^GAP \((?!0\))\d+\)/)
+          text.is_a?(String) && text.match?(NONZERO_GAP_HEADING)
         end
 
         # Mints the `run` key a creating command was not given, when the domain opted in.
@@ -224,10 +229,10 @@ module Hecks
         # record. When no identity adapter is bound the run is refused, saying to name a key,
         # rather than sent on without one.
         #
-        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+        # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted domain
         # @param spec [Hash] the command's projected spec
         # @param args [Hash] the parsed arguments
-        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @param settings [Hash, nil] the bluebook's `launcher` setting
         # @return [Array(Hash, String)] the arguments, and the key minted (nil when none was)
         # @raise [Runtime::NotFound] if a key is owed but no identity adapter is bound
         def run_key(runtime, spec, args, settings)
@@ -236,10 +241,10 @@ module Hecks
           key = Ports::IdentityGeneration.uuid(runtime.registry)
           [args.merge(run: { value: key }), key]
         rescue Runtime::WiringError => e
-          raise Runtime::NotFound, "cannot mint a run key (#{e.message.lines.first.strip}); name one with run=<key>"
+          raise Runtime::NotFound, "cannot mint a run key (#{Text.first_line(e.message)}); name one with run=<key>"
         end
 
-        # Whether the command is a creating one of an opted-in chapter, takes a run key and was
+        # Whether the command is a creating one of an opted-in bluebook, takes a run key and was
         # given none.
         # @api private
         def key_owed?(runtime, spec, args, settings)
@@ -253,10 +258,10 @@ module Hecks
         #
         # @param aggregate [Bluebook::Aggregate, nil] the record's aggregate
         # @param state [Hash, nil] the record's state
-        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @param settings [Hash, nil] the bluebook's `launcher` setting
         # @return [Boolean] false when the aggregate has no lifecycle
         def failed?(aggregate, state, settings)
-          field = aggregate&.lifecycle&.field
+          field = aggregate&.lifecycle_field
           return false unless field && state && settings
 
           Array(aggregate.lifecycle.marked(FAILURE_MARK)).include?(state[field.to_sym].to_s)

data/lib/hecks/adapters/driving/mcp_scope/env_problems.rb

@@ -1,3 +1,5 @@
+require_relative "../../../text"
+
 module Hecks
   module Adapters
     module Driving
@@ -61,7 +63,7 @@ module Hecks
 
           def split_paths(value) = value.to_s.split(File::PATH_SEPARATOR).reject(&:empty?)
 
-          def split_names(value) = value.to_s.split(",").map(&:strip).reject(&:empty?).uniq
+          def split_names(value) = Text.comma_list(value).uniq
         end
       end
     end

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

@@ -27,12 +27,13 @@ module Hecks
 
         # Argument names a restricted server never passes on, whatever command carries them: each
         # one
-        # names a host or a URL, a binary to run, a place to write, a port to open, a store to
-        # switch to, or flips a command from a preview to a change of state.
+        # names a host or a URL, a binary to run, what a spawned session is told to do, a place to
+        # write, a port to open, a store to switch to, or flips a command from a preview to a
+        # change of state.
         DENIED_ARGUMENTS = %w[
-          adapter artifact confirm expected from gem_only header health_path host live no_wait npm_local
-          npm_only output path payload payload_file port rust_binary scheme stage_dir state_path stdio url
-          write
+          adapter artifact brief claimed confirm expected from gem_only header health_path host live no_wait npm_local
+          npm_only output path payload payload_file port prebuilt remote row rust_binary scheme stage_dir state_path
+          stdio url write
         ].freeze
 
         # Argument names whose values are paths (a comma-separated list for some). A restricted
@@ -40,11 +41,11 @@ module Hecks
         # passes them on only when each resolves, symlinks followed, inside `Storehouse::BOOT_ROOT`,
         # and holds no colon: `host:repo` and `https://host/x` would otherwise pass as relative
         # paths.
-        PATH_ARGUMENTS = %w[dir domain domains file fixture paths root script].freeze
+        PATH_ARGUMENTS = %w[checkout dir directory domain domains file fixture paths repo root script].freeze
 
         # Argument names whose values are git refs: plain names only, so a value cannot read as an
         # option to git.
-        REF_ARGUMENTS = %w[commit ref].freeze
+        REF_ARGUMENTS = %w[branch commit onto ref].freeze
 
         # What a plain git ref looks like: no leading dash, no `..`, no spaces.
         PLAIN_REF = %r{\A[A-Za-z0-9][A-Za-z0-9._/~^@-]*\z}

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

@@ -5,7 +5,7 @@ module Hecks
     module Driving
       # The launcher's help for someone starting out: a folder with no bluebook in it has no use yet
       # for the commands that act on a domain, so the help lists only the `newcomer` commands the
-      # chapter's `launcher` setting names (`hecks --all` lists the rest).
+      # bluebook's `launcher` setting names (`hecks --all` lists the rest).
       module Newcomer
         # How deep under a directory a bluebook may sit and still make it a project:
         # `Hecks.bluebook` beside it, or `bluebook/pizzas.bluebook` one folder down, as the
@@ -25,15 +25,16 @@ module Hecks
           PROJECT_GLOBS.none? { |pattern| bluebook_under?(dir, pattern) }
         end
 
-        # The help options a newcomer gets: only the setting's `newcomer` commands, and no chapters.
+        # The help options a newcomer gets: only the setting's `newcomer` commands, and no
+        # bluebooks.
         #
-        # @param settings [Hash, nil] the chapter's `launcher` setting
-        # @return [Hash{Symbol => Object}, nil] `:only` and `:chapters`, or nil when the chapter
+        # @param settings [Hash, nil] the bluebook's `launcher` setting
+        # @return [Hash{Symbol => Object}, nil] `:only` and `:bluebooks`, or nil when the bluebook
         #   names no newcomer commands
         def audience(settings)
           return unless settings && settings[:newcomer]
 
-          { only: Array(settings[:newcomer]).map(&:to_s), chapters: [] }
+          { only: Array(settings[:newcomer]).map(&:to_s), declarations: [] }
         end
 
         # Whether `pattern` finds a bluebook under `dir`; a folder the person may not read holds

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

@@ -5,6 +5,8 @@ require_relative "../../../bluebook/dsl/const_shim"
 require_relative "../../../bluebook/dsl/binding_proxy"
 require_relative "../../../bluebook/hecksagon"
 require_relative "../handle"
+require_relative "bulk_verbs"
+require_relative "query_rows"
 require_relative "../../../naming"
 
 module Hecks
@@ -40,19 +42,17 @@ module Hecks
               end
             end
 
-            # A query is a bare module method (no `!`): it just reads and returns
-            # the same raw row array `dispatcher.query` itself answers.
-            aggregate.queries.each do |query|
-              mod.define_singleton_method(Naming.snake(query.hecks_name)) do |**args|
-                dispatcher.query("#{fqn}.#{query.hecks_name}", **args)
-              end
-            end
+            # Every other command's bang form sends it to every row a query answered (ADR 0125).
+            BulkVerbs.define(mod, dispatcher, domain, aggregate)
+            # A query is a bare module method (no `!`): it reads and returns the raw rows
+            # `dispatcher.query` answers, as `QueryRows` so a bulk run can name the query.
+            BulkVerbs.define_queries(mod, dispatcher, fqn, aggregate)
 
             mod.define_singleton_method(:fqn)        { fqn }
             mod.define_singleton_method(:ir)         { aggregate }
 
             # Every construct emits its own IR, so an aggregate is a legitimate
-            # `project` target too. A chapter-scoped target refuses here via
+            # `project` target too. A bluebook-scoped target refuses here via
             # `Projector.admits!` rather than answering a confidently empty result.
             mod.define_singleton_method(:project) do |target, out: nil, **options|
               key      = Projector.key_for(target)
@@ -66,7 +66,7 @@ module Hecks
               aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort
             end
             mod.define_singleton_method(:queries) { aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
-            # This chapter's own `:docs` projection, narrowed to this aggregate.
+            # This bluebook's own `:docs` projection, narrowed to this aggregate.
             mod.define_singleton_method(:docs) do |**options|
               Projector.call(:docs, bluebook: dispatcher.registry.bluebook(domain),
                                     options:  options.merge(aggregate: aggregate.hecks_name))
@@ -85,7 +85,8 @@ module Hecks
             end
 
             mod.define_singleton_method(:all) do |**opts|
-              dispatcher.registry.repository(domain, aggregate).all(**opts).map do |instance|
+              repository = dispatcher.registry.repository(domain, aggregate)
+              repository.all(**opts).map do |instance|
                 Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: instance)
               end
             end
@@ -120,8 +121,8 @@ module Hecks
 
             # `BindingProxy#ask_via` for a repeat boot, when this module stands where the proxy is.
             mod.define_singleton_method(:ask_via) do |name, port:|
-              chapter = Hecks.current_registry&.bluebook(domain)
-              Bluebook::AskResolution.pick!(chapter, aggregate.hecks_name, name, port)
+              declaration = Hecks.current_registry&.bluebook(domain)
+              Bluebook::AskResolution.pick!(declaration, aggregate.hecks_name, name, port)
               self
             end
 

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

@@ -0,0 +1,127 @@
+require "securerandom"
+require_relative "../../../naming"
+require_relative "../../../runtime/errors"
+require_relative "../../../bulk/plan"
+require_relative "../handle"
+require_relative "query_rows"
+
+module Hecks
+  module Adapters
+    module Driving
+      module Ruby
+        # The bulk form of an aggregate's non-creating commands (ADR 0125): a module method per
+        # command that sends it to every row a query answered, through the Bulk bluebook's
+        # `BulkRun`.
+        #
+        #     Account.freeze_account!(over: Account.open_for_customer(reference: "C-1"))
+        module BulkVerbs
+          # The bluebook whose `BulkRun` records every run.
+          BLUEBOOK = "Bulk".freeze
+
+          module_function
+
+          # Defines `name!(over:)` on `mod` for each command of `aggregate` that does not
+          # create its record. Called without `over:`, it says what the bulk form is
+          # ({refuse_unaimed!}).
+          #
+          # @param mod [Module] the aggregate module being built
+          # @param dispatcher [Runtime::Dispatcher] the booted dispatcher the runs go through
+          # @param domain [String] the aggregate's bluebook
+          # @param aggregate [Bluebook::Aggregate] the aggregate whose commands get a bulk form
+          # @return [void]
+          def define(mod, dispatcher, domain, aggregate)
+            aggregate.commands.reject(&:creates?).each do |command|
+              verb = "#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}"
+              mod.define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |over: nil|
+                BulkVerbs.refuse_unaimed!(command, over)
+                BulkVerbs.run(dispatcher, verb, over)
+              end
+            end
+          end
+
+          # Defines a bare module method per query of `aggregate`, answering its rows as
+          # {QueryRows}, so the answer can be handed to a bulk form as `over:`.
+          #
+          # @param mod [Module] the aggregate module being built
+          # @param dispatcher [Runtime::Dispatcher] the booted dispatcher the queries go through
+          # @param fqn [String] the aggregate's qualified name, `"Domain::Aggregate"`
+          # @param aggregate [Bluebook::Aggregate] the aggregate whose queries get a method
+          # @return [void]
+          def define_queries(mod, dispatcher, fqn, aggregate)
+            aggregate.queries.each do |query|
+              verb = "#{fqn}.#{query.hecks_name}"
+              mod.define_singleton_method(Naming.snake(query.hecks_name)) do |**args|
+                QueryRows.new(dispatcher.query(verb, **args), verb: verb, arguments: args)
+              end
+            end
+          end
+
+          # Requests one bulk run and answers its record once every row has been sent.
+          #
+          # @param dispatcher [Runtime::Dispatcher] the booted dispatcher
+          # @param verb [String] the command each row receives
+          # @param over [QueryRows] what a query method answered
+          # @return [Handle] the `Bulk::BulkRun` record: `status`, and `results` per row
+          # @raise [ArgumentError] if `over` is not what a query method answered
+          # @raise [Runtime::WiringError] if Bulk is not attached, or the run was declined
+          #   before any row was sent
+          def run(dispatcher, verb, over)
+            refuse_unnamed_query!(over)
+            bulk = bulk_aggregate(dispatcher.registry, verb)
+            run = SecureRandom.uuid
+            dispatcher.dispatch_flat("#{BLUEBOOK}::BulkRun.Request", **request(run, verb, over))
+            declined!(record(dispatcher, bulk, run))
+          end
+
+          # The `Request` facts for one run.
+          def request(run, verb, over)
+            { run: { value: run }, verb: { value: verb }, over: { value: over.verb },
+              arguments: Bulk::Plan.argument_rows(over.arguments) }
+          end
+
+          # Says what the bulk form is when it is called without `over:`, the usual sign that the
+          # caller meant the one-record form on a command that takes no attributes.
+          #
+          # @param command [Bluebook::Command] the command whose bang form was called
+          # @param over [QueryRows, nil] what the caller handed `over:`
+          # @raise [ArgumentError] if `over` is nil
+          def refuse_unaimed!(command, over)
+            return unless over.nil?
+
+            name = "#{Naming.snake(command.hecks_name)}!"
+            raise ArgumentError,
+                  "#{name} on the aggregate module is the bulk form and needs over: a query, such as " \
+                  "#{name.delete_suffix("!")}!(over: Aggregate.some_query). To send #{command.hecks_name} " \
+                  "to one record, call #{name} on that record's handle"
+          end
+
+          def refuse_unnamed_query!(over)
+            return if over.is_a?(QueryRows)
+
+            raise ArgumentError, "over: takes what a query method answers, such as Account.open — " \
+                                 "a #{over.class} names no query to run"
+          end
+
+          def bulk_aggregate(registry, verb)
+            registry.bluebook(BLUEBOOK)&.aggregate("BulkRun") or
+              raise Runtime::WiringError, "#{verb} over a query needs the Bulk bluebook: " \
+                                          "add `attaches \"Bulk\"` to the domain's hecksagon"
+          end
+
+          def record(dispatcher, bulk, run)
+            instance = dispatcher.registry.repository(BLUEBOOK, bulk).find(run)
+            Handle.new(dispatcher: dispatcher, domain: BLUEBOOK, aggregate: bulk, instance: instance)
+          end
+
+          # The run, unless it was declined before any row was sent: that is wiring, not a
+          # row's refusal.
+          def declined!(handle)
+            return handle unless handle.status == "declined"
+
+            raise Runtime::WiringError, Bulk::Plan.plain(handle[:refusal]&.to_h)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/ruby/{chapter.rb → declaration.rb}

@@ -6,62 +6,62 @@ module Hecks
   module Adapters
     module Driving
       module Ruby
-        # One chapter's module: vision and aggregate list on the singleton, one
+        # One bluebook's module: vision and aggregate list on the singleton, one
         # aggregate module per declared head, and a `const_missing` hook for undeclared names.
-        module Chapter
-          # Builds the anonymous module that stands for one booted chapter: `vision`,
+        module Declaration
+          # Builds the anonymous module that stands for one booted bluebook: `vision`,
           # `aggregates`, `docs`, `narrate` and `project` as singleton methods, plus one
           # nested constant per aggregate holding that aggregate module.
           #
-          # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+          # @param dispatcher [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted
           #   dispatcher each aggregate module closes over
-          # @param bluebook [Bluebook::Chapter] the chapter to project into a module
+          # @param bluebook [Bluebook::Declaration] the bluebook to project into a module
           # @return [Module] a fresh, unnamed module; `Ruby.install` gives it its
           #   top-level name
           # @raise [NameError] if an aggregate's name is not a valid constant name
-          def chapter_module(dispatcher, bluebook)
-            chapter = Module.new
-            define_readers(chapter, bluebook)
-            define_projections(chapter, bluebook)
+          def bluebook_module(dispatcher, bluebook)
+            declaration = Module.new
+            define_readers(declaration, bluebook)
+            define_projections(declaration, bluebook)
 
             bluebook.aggregates.each do |aggregate|
-              chapter.const_set(aggregate.hecks_name, aggregate_module(dispatcher, bluebook.name, aggregate))
+              declaration.const_set(aggregate.hecks_name, aggregate_module(dispatcher, bluebook.name, aggregate))
             end
 
-            define_const_missing(chapter, bluebook)
-            chapter
+            define_const_missing(declaration, bluebook)
+            declaration
           end
 
           private
 
-          # The chapter's vision and its aggregate names.
-          def define_readers(chapter, bluebook)
-            chapter.define_singleton_method(:vision)     { bluebook.vision }
-            chapter.define_singleton_method(:aggregates) { bluebook.aggregates.map(&:name).sort }
+          # The bluebook's vision and its aggregate names.
+          def define_readers(declaration, bluebook)
+            declaration.define_singleton_method(:vision)     { bluebook.vision }
+            declaration.define_singleton_method(:aggregates) { bluebook.aggregates.map(&:name).sort }
           end
 
-          # The chapter's documents and projections, each projected from its IR on every call so
+          # The bluebook's documents and projections, each projected from its IR on every call so
           # none can go stale.
-          def define_projections(chapter, bluebook)
-            chapter.define_singleton_method(:docs) do |**options|
+          def define_projections(declaration, bluebook)
+            declaration.define_singleton_method(:docs) do |**options|
               Projector.call(:docs, bluebook: bluebook, options: options)
             end
 
-            # The chapter read back in english, via `Projector::NarrateProjector`.
-            chapter.define_singleton_method(:narrate) do |**options|
+            # The bluebook read back in english, via `Projector::NarrateProjector`.
+            declaration.define_singleton_method(:narrate) do |**options|
               Projector.call(:narrate, bluebook: bluebook, options: options)
             end
 
-            define_project(chapter, bluebook)
+            define_project(declaration, bluebook)
           end
 
-          # Projects the chapter's IR through a target; `out:` writes the artifact and
+          # Projects the bluebook's IR through a target; `out:` writes the artifact and
           # the remaining options go to the projector (`audience:` for OIDC).
           #
           #   Pizzas.project(Projections::OIDC)
           #   Pizzas.project(Projections::Shape, out: "shape.json")
-          def define_project(chapter, bluebook)
-            chapter.define_singleton_method(:project) do |target, out: nil, **options|
+          def define_project(declaration, bluebook)
+            declaration.define_singleton_method(:project) do |target, out: nil, **options|
               key      = Projector.key_for(target)
               artifact = Projector.call(key, bluebook: bluebook, options: options)
               return artifact unless out
@@ -73,8 +73,8 @@ module Hecks
           # Inside a hecksagon a name is a declaration: with a collector open it becomes
           # a `BindingProxy`. Otherwise a scoped reference from a bluebook mid-declaration
           # goes to the `ConstShim` resolver, so it resolves whether or not a facade exists.
-          def define_const_missing(chapter, bluebook)
-            chapter.define_singleton_method(:const_missing) do |name|
+          def define_const_missing(declaration, bluebook)
+            declaration.define_singleton_method(:const_missing) do |name|
               collector = Bluebook::DSL::HecksagonBuilder.collector
               return Bluebook::DSL::BindingProxy.new("#{bluebook.name}::#{name}", collector) if collector
 

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

@@ -0,0 +1,27 @@
+module Hecks
+  module Adapters
+    module Driving
+      module Ruby
+        # What an aggregate module's query method answers: the rows, as an Array, that also
+        # remember the query and the arguments they were asked with, so a bulk run handed them
+        # (`over:`) runs that query itself rather than a list read earlier (ADR 0125).
+        class QueryRows < Array
+          # @return [String] the query's verb, `"Domain::Aggregate.Query"`
+          attr_reader :verb
+
+          # @return [Hash{Symbol => Object}] the arguments the query was asked with
+          attr_reader :arguments
+
+          # @param rows [Array<Hash>] the rows the query answered
+          # @param verb [String] the query's verb
+          # @param arguments [Hash{Symbol => Object}] the arguments it was asked with
+          def initialize(rows, verb:, arguments:)
+            super(rows)
+            @verb      = verb
+            @arguments = arguments
+          end
+        end
+      end
+    end
+  end
+end