hecks 7.0.0 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5513321d2ace0e5e35b6b806fd04f8421e41d713a49667511c278309892a3ec8
-  data.tar.gz: b440aca95a39f41a04375a879b917fd153e6277bba6386a1f637e87c2288f225
+  metadata.gz: 9d11764e3755dd6389e6266151066f1436a4d1d645b4d4224aa3873b6f98a62f
+  data.tar.gz: 87208f597ea96b9cff0d938c8690389b78b91c4d0e00d126febfe75615d54ed1
 SHA512:
-  metadata.gz: e318b100521c095c1ee8c0962e5108ffe5595281bc9261de0cf8460306c4144b9c5465ef48c6a455c923175b1bc027bcee34d90ea127f5c201d882b427c95169
-  data.tar.gz: 1fede9423b4f0dfd0b95a15d7be5ee3b651d0dfdab3b7430f7f4a3f4292e343c8c9c03babbc8c9d52412a76d38914405190fcf37bdd0ab6090f3d27b005daf1c
+  metadata.gz: f47097c7ee7c848c84c4a4cbaadf5163a1018cc3af9f0f5ffefc6cf03d600554e7e61c04584e5a381b55ad67a22f1585cd46da7edc85ceb2b8d9f8266e9a14b6
+  data.tar.gz: 0ccc3310e227fb052f12b40777fe149e58c097c9c756f856e48db1f08dcc6552dc52014f0d98b26d66f24907f3c16e3f7ea12e19f2259d6ab27271a0fb8b58d1

data/lib/hecks/adapters/driven/postgres_era/lineage/chain_sql.rb

@@ -82,7 +82,8 @@ module Hecks
             layered_chain_sql(aggregate, era, edges) || walked_sql(aggregate, era, edges, direct)
           end
 
-          # The whole chain from the journal: one composed step when `direct` and the chain composes,
+          # The whole chain from the journal: one composed step when `direct` and the chain
+          # composes,
           # otherwise one link per era.
           def walked_sql(aggregate, era, edges, direct)
             (direct && direct_chain_sql(aggregate, era, edges)) || chain_sql(aggregate, era, edges)

data/lib/hecks/adapters/driven/postgres_era/lineage/provisioning.rb

@@ -20,7 +20,8 @@ module Hecks
           # REVOKE are owner-only, so a non-owner app role must skip them.
           #
           # @return [void]
-          # @raise [Runtime::WiringError] if the domain's `formerly_known_as` rename is still pending
+          # @raise [Runtime::WiringError] if the domain's `formerly_known_as` rename is still
+          #   pending
           # @raise [PG::Error] if Postgres refuses a provisioning statement
           def ensure_base!
             refuse_pending_rename!
@@ -120,7 +121,8 @@ module Hecks
             # Canonical-form version that minted the name (Runtime::StorageShape::FORM_VERSION);
             # NULL reads as 1.
             @db.exec("ALTER TABLE hecks_eras ADD COLUMN IF NOT EXISTS canon_form int")
-            # The edge an era was minted under when no edge file wrote it, as `Translation::ImplicitEdge::RECORD`;
+            # The edge an era was minted under when no edge file wrote it, as
+            # `Translation::ImplicitEdge::RECORD`;
             # NULL for every era a written edge reached.
             @db.exec("ALTER TABLE hecks_eras ADD COLUMN IF NOT EXISTS edge jsonb")
             @db.exec(ERA_TEXTS_SQL)

data/lib/hecks/adapters/driven/postgres_era/lineage/split_sql.rb

@@ -2,11 +2,14 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
-        # ADR 0166: a `split` writes rows into another aggregate from one aggregate's rows. The target's
-        # head is not stored: its tail is the source's held-era state, fanned out one row per target key,
+        # ADR 0166: a `split` writes rows into another aggregate from one aggregate's rows. The
+        # target's
+        # head is not stored: its tail is the source's held-era state, fanned out one row per target
+        # key,
         # and read through the same chain every head reads.
         module SplitSql
-          # The source's rows as they are in the era the split edge starts from, latest per id, with the
+          # The source's rows as they are in the era the split edge starts from, latest per id, with
+          # the
           # era kept so later edges' guards still hold.
           SPLIT_SOURCE_SQL = <<~SQL.freeze
             WITH tail AS MATERIALIZED (%<tail>s),
@@ -14,7 +17,8 @@ module Hecks
             SELECT ordinal, era, aggregate_id, operation, state FROM edge_%<last>s
           SQL
 
-          # The split edge that creates `names[:current][n]`, with the source aggregate and the split, or nil.
+          # The split edge that creates `names[:current][n]`, with the source aggregate and the
+          # split, or nil.
           def split_into(names, edges)
             edges.each_with_index do |edge, index|
               target = names[:current][index + 1]
@@ -26,7 +30,8 @@ module Hecks
             nil
           end
 
-          # The target's tail from its source's held-era rows: the source is chained through the edges
+          # The target's tail from its source's held-era rows: the source is chained through the
+          # edges
           # before the split edge, so the split reads the shape it declares its fields in.
           def split_tail_sql(names, edges)
             found = split_into(names, edges)
@@ -36,7 +41,8 @@ module Hecks
             split_fanout_sql(source_sql, found[:split], names[:storage][found[:index] + 1])
           end
 
-          # A split target's records as its split fans them out of the source, latest per id, or nil when
+          # A split target's records as its split fans them out of the source, latest per id, or nil
+          # when
           # the aggregate is not a split target: the "before" side of the audit of a split edge.
           def split_latest(aggregate, edges)
             tail = split_tail_sql(names_by_era(aggregate, edges), edges)
@@ -57,8 +63,10 @@ module Hecks
             format(SPLIT_SOURCE_SQL, tail: tail, chain: chain.join(",\n"), last: edges.size)
           end
 
-          # One row per source row that carries the key: the key becomes the target's id, and the named
-          # fields are copied under their own names. Deletes are kept, so a deleted source deletes its
+          # One row per source row that carries the key: the key becomes the target's id, and the
+          # named
+          # fields are copied under their own names. Deletes are kept, so a deleted source deletes
+          # its
           # target row too.
           def split_fanout_sql(source_sql, split, target_storage)
             key = text_literal(split.keyed_by.to_s)

data/lib/hecks/adapters/driven/postgres_era/lineage/transform_sql.rb

@@ -3,6 +3,10 @@ module Hecks
     class PostgresEra
       class Lineage
         # The six shared `hecks_tr_*` jsonb functions that compiled translation SQL calls.
+        #
+        # A function that calls another `hecks_tr_*` function keeps the search path it was
+        # installed under (`SET search_path FROM CURRENT`), so it finds its sibling when the
+        # caller's path is empty, as in a `pg_restore` refreshing the views built on them.
         module TransformSql
           # Splits a path out of a state, answering what remains, the value and whether it was
           # there.
@@ -69,7 +73,7 @@ module Hecks
           # Moves the value at one path to another.
           TR_MOVE_SQL = <<~SQL.freeze
             CREATE OR REPLACE FUNCTION hecks_tr_move(state jsonb, from_path text[], to_path text[], rule_label text) RETURNS jsonb
-            LANGUAGE plpgsql IMMUTABLE AS $fn$
+            LANGUAGE plpgsql IMMUTABLE SET search_path FROM CURRENT AS $fn$
             DECLARE extracted record;
             BEGIN
               SELECT * INTO extracted FROM hecks_tr_extract(state, from_path);
@@ -81,7 +85,7 @@ module Hecks
           # Moves a value to another path, mapping it through a lookup table.
           TR_CONVERT_SQL = <<~SQL.freeze
             CREATE OR REPLACE FUNCTION hecks_tr_convert(state jsonb, from_path text[], to_path text[], pairs jsonb, from_label text, rule_label text) RETURNS jsonb
-            LANGUAGE plpgsql IMMUTABLE AS $fn$
+            LANGUAGE plpgsql IMMUTABLE SET search_path FROM CURRENT AS $fn$
             DECLARE extracted record; pair jsonb;
             BEGIN
               SELECT * INTO extracted FROM hecks_tr_extract(state, from_path);
@@ -99,7 +103,7 @@ module Hecks
           # Removes the value at a path.
           TR_DROP_SQL = <<~SQL.freeze
             CREATE OR REPLACE FUNCTION hecks_tr_drop(state jsonb, path text[]) RETURNS jsonb
-            LANGUAGE plpgsql IMMUTABLE AS $fn$
+            LANGUAGE plpgsql IMMUTABLE SET search_path FROM CURRENT AS $fn$
             DECLARE extracted record;
             BEGIN
               SELECT * INTO extracted FROM hecks_tr_extract(state, path);

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/era_resolver.rb

@@ -46,7 +46,8 @@ module Hecks
 
           private
 
-          # Opens the lineage: for reading on a boot, and provisioned first on a mint request. Either
+          # Opens the lineage: for reading on a boot, and provisioned first on a mint request.
+          # Either
           # refuses, by name, while the domain's history still sits under its former name.
           def open_lineage(db, bluebook, settings, request)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as,

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/mint_request.rb

@@ -3,7 +3,8 @@ module Hecks
     class PostgresEra
       module LineageManager
         # The request a mint carries into the era check: whether the mint was confirmed, the verdict
-        # the rehearsal of that same era reached, and the ledger watermark the rehearsal read. Only the
+        # the rehearsal of that same era reached, and the ledger watermark the rehearsal read. Only
+        # the
         # Maintenance mint path builds one; a boot has none, so a boot that would mint refuses.
         MintRequest = Data.define(:confirm, :verdict, :watermark) do
           # Reads the request out of a settings hash, spelled with symbol or string keys.

data/lib/hecks/adapters/driven/postgres_era/lineage_manager/refusals.rb

@@ -32,7 +32,8 @@ module Hecks
                                        "persisted_by block of its world", minting: false)
           end
 
-          # Refuses a mint that the rehearsal does not back: not confirmed, not a would_mint verdict, or a
+          # Refuses a mint that the rehearsal does not back: not confirmed, not a would_mint
+          # verdict, or a
           # ledger watermark that moved since the rehearsal read it.
           def refuse_unrehearsed_mint!(context)
             request = context.mint_request

data/lib/hecks/adapters/driving/cli_runner/bang_rule.rb

@@ -10,6 +10,9 @@ module Hecks
             CliRunner::QUERY_WORDS.include?(argv.first) ? argv[1] : argv.first
           end
 
+          # Whether a query shares its name with a command, the one case `query` is typed.
+          def shared?(scope, name, asking) = asking && scope[:cli][:names][:command].key?(name)
+
           # The answer a line gets before any command runs: its help, or its refusal for a
           # command written without its bang.
           def early_answer(scope, cli, line)

data/lib/hecks/adapters/driving/cli_runner/completion_words.rb

@@ -5,6 +5,8 @@ module Hecks
         # The launcher word `completion <shell>` (ADR 0163, plan step 7): the script that completes
         # the launcher's words in that shell, written from the same listing the help prints.
         module CompletionWords
+          USAGE = "completion <bash|zsh|fish>  print the script that completes the launcher in a shell".freeze
+
           # The answer to `completion <shell>`: the script on stdout, or the usage line when the
           # shell is missing or not one this projection writes.
           def completion_answer(scope, argv)

data/lib/hecks/adapters/driving/cli_runner/read_context.rb

@@ -2,9 +2,12 @@ module Hecks
   module Adapters
     module Driving
       module CliRunner
-        # The session's checkout, for reads only. A read of a checkout's state that names no checkout
-        # takes the one the session set in `HECKS_CHECKOUT`; a command never does. A command names its
-        # own target, because a write must land where it was asked to, not where the session last was.
+        # The session's checkout, for reads only. A read of a checkout's state that names no
+        # checkout
+        # takes the one the session set in `HECKS_CHECKOUT`; a command never does. A command names
+        # its
+        # own target, because a write must land where it was asked to, not where the session last
+        # was.
         module ReadContext
           # The environment variable a session sets to name its checkout.
           VARIABLE = "HECKS_CHECKOUT".freeze

data/lib/hecks/adapters/driving/cli_runner/renamed_names.rb

@@ -6,7 +6,8 @@ module Hecks
         # is noted once on standard error, and its argument names translate before the command reads
         # them. Extended into `CliRunner`.
         module RenamedNames
-          # Notes a renamed spelling once, and returns the line's argv with its arguments translated.
+          # Notes a renamed spelling once, and returns the line's argv with its arguments
+          # translated.
           #
           # @param cli [Hash] the projection, holding `:names` with its `:renamed` table
           # @param typed [String] the word typed, without its `!`

data/lib/hecks/adapters/driving/cli_runner/resolution.rb

@@ -33,7 +33,7 @@ module Hecks
           # The answer a line gets without naming a command, or nil when it names one.
           def answer_for(scope, argv)
             json_answer(scope, argv) || usage_answer(scope, argv.first) || module_answer(scope, argv.first) ||
-              search_answer(scope, argv) || completion_answer(scope, argv) || tour_answer(scope, argv) || resume(scope, argv)
+              word_answer(scope, argv)
           end
 
           # The answer to a line that is only a request for usage, or nil.
@@ -82,7 +82,7 @@ module Hecks
 
           # The usage of one command or question, which its `--help` asks for.
           def command_help(scope, name, asking)
-            options = scope[:options].merge(command: name, ask: asking)
+            options = scope[:options].merge(command: name, ask: asking, query_word: shared?(scope, name, asking))
             Projector.call(:cli, bluebook: scope[:bluebook], options: options)[:usage]
           end
 

data/lib/hecks/adapters/driving/cli_runner/resume_words.rb

@@ -8,6 +8,7 @@ module Hecks
         # dispatched with the saved arguments through the ordinary line path.
         module ResumeWords
           SAGA = "GateAndBoard".freeze
+          USAGE = "resume <run>  continue a GateAndBoard saga that faulted, from the stage it faulted in".freeze
 
           # The answer to `resume <run>`, or nil when the line is not a resume.
           def resume(scope, argv)

data/lib/hecks/adapters/driving/cli_runner/run_reference.rb

@@ -5,7 +5,8 @@ module Hecks
     module Driving
       module CliRunner
         # Lets a landing name the linked worktree it lands by its run id, rather than repeating its
-        # checkout and branch. An explicit checkout or branch always wins over the one the worktree holds.
+        # checkout and branch. An explicit checkout or branch always wins over the one the worktree
+        # holds.
         module RunReference
           # The aggregate whose record a landing's `from` names.
           SOURCE = "LinkedTree".freeze
@@ -29,7 +30,8 @@ module Hecks
           # @param runtime [Runtime::Registry] the booted domain the command runs against
           # @param spec [Hash] the resolved command
           # @param args [Hash] the parsed arguments, keyed by name
-          # @return [Hash] the arguments, with checkout and branch filled from the named worktree when the
+          # @return [Hash] the arguments, with checkout and branch filled from the named worktree
+          #   when the
           #   caller gave a `from` and left them out
           def fill(runtime, spec, args)
             from = args[:from]&.fetch(:value, nil)
@@ -44,7 +46,8 @@ module Hecks
                        branch:   args[:branch] || { value: value_of(record[:branch]) })
           end
 
-          # The ids a result names: the run key, the record written, and the references the command used,
+          # The ids a result names: the run key, the record written, and the references the command
+          # used,
           # with the checkout and branch it resolved. Absent ones are left out.
           #
           # @param args [Hash] the arguments the command ran with, after any reference was filled

data/lib/hecks/adapters/driving/cli_runner/search_words.rb

@@ -5,6 +5,8 @@ module Hecks
         # The launcher word `search`: the commands and queries a word appears in, read from the same
         # projection the help prints (ADR 0163, step 20). Extended into `CliRunner`.
         module SearchWords
+          USAGE = "search <word> [--all]  list the commands and queries a word appears in".freeze
+
           # The answer to `search <word> [--all]`: the commands and queries a word appears in, or
           # the line saying none does.
           def search_answer(scope, argv)

data/lib/hecks/adapters/driving/cli_runner/tour_words.rb

@@ -12,6 +12,7 @@ module Hecks
           TOUR_NAME = "Tour".freeze
           TOUR_COMMAND = %w[Example.create! name=hello].freeze
           TOUR_DIRECTORY = "hecks-tour".freeze
+          USAGE = "tour [dir]  write a sample domain in dir (default hecks-tour) and run one command".freeze
 
           # The answer to `tour [dir]`, or nil when the line is not a tour.
           def tour_answer(scope, argv)

data/lib/hecks/adapters/driving/cli_runner/verb_names.rb

@@ -9,7 +9,8 @@ module Hecks
           # A realm written before the aggregate: `Hecks::`.
           REALM = /\A(?:[A-Z]\w*::)+/
 
-          # The spelling notices this process has already printed, keyed by the spelling typed, so each
+          # The spelling notices this process has already printed, keyed by the spelling typed, so
+          # each
           # prints once.
           NOTED = Set.new
 

data/lib/hecks/adapters/driving/cli_runner/verbosity.rb

@@ -65,6 +65,8 @@ module Hecks
 
           # @return [String] the context line, as `-v` prints it
           def checkout_line
+            require_relative "../context_line"
+            require_relative "../../../hecks/adapters/settings_reading"
             ContextLine.line(directory: Dir.pwd, stores: SettingsReading.new.stores(Dir.pwd),
                              audience: ContextLine.audience(Dir.pwd))
           end

data/lib/hecks/adapters/driving/cli_runner/word_help.rb

@@ -0,0 +1,40 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Help for the launcher words that read their own arguments (`tour`, `search`, `completion`,
+        # `resume`). A line that asks for help after the word answers the word's one-line usage
+        # before the word's handler runs, so `hecks tour --help` never writes a directory named
+        # `--help`. Extended into `CliRunner`.
+        module WordHelp
+          # The usage line of each word, declared by the word's own module.
+          #
+          # @return [Hash{String => String}] the word and its usage
+          def word_usages
+            { "tour" => TourWords::USAGE, "search" => SearchWords::USAGE,
+              "completion" => CompletionWords::USAGE, "resume" => ResumeWords::USAGE }
+          end
+
+          # The answer to a line that opens with one of these words: its usage when it asks for
+          # help,
+          # else the word's own handler; nil when the line opens with another word.
+          def word_answer(scope, argv)
+            word_help(scope, argv) || search_answer(scope, argv) || completion_answer(scope, argv) ||
+              tour_answer(scope, argv) || resume(scope, argv)
+          end
+
+          # The answer to `<word> --help`, `<word> -h` or `<word> help`, or nil when the line asks
+          # for no help or its first word is not one of these.
+          #
+          # @return [Hash, nil] `{answer: [text, status]}`
+          def word_help(scope, argv)
+            usage = word_usages[argv.first]
+            return unless usage && argv.drop(1).intersect?(Resolution::HELP_WORDS)
+
+            { answer: ["usage: #{scope[:program]} #{usage}", ExitStatus::ANSWERED] }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -16,6 +16,7 @@ require_relative "cli_runner/search_words"
 require_relative "cli_runner/completion_words"
 require_relative "cli_runner/tour_words"
 require_relative "cli_runner/resume_words"
+require_relative "cli_runner/word_help"
 require_relative "cli_runner/json_words"
 require_relative "cli_runner/settling"
 require_relative "cli_runner/streaming"
@@ -45,6 +46,7 @@ module Hecks
         extend CompletionWords
         extend TourWords
         extend ResumeWords
+        extend WordHelp
         extend JsonWords
         extend Suggestions
         extend NameIndex

data/lib/hecks/adapters/driving/mcp/progress_sink.rb

@@ -5,9 +5,11 @@ module Hecks
   module Adapters
     module Driving
       module Mcp
-        # Where a stage's progress lines go when the client asked for them with a progress token: each
+        # Where a stage's progress lines go when the client asked for them with a progress token:
+        # each
         # line becomes one `notifications/progress` message on the server's output, ahead of the
-        # response to the call. Stands in for the standard error that `Tools::StageProgress` writes to.
+        # response to the call. Stands in for the standard error that `Tools::StageProgress` writes
+        # to.
         class ProgressSink
           # @param token [Object] the client's `progressToken`, echoed back on every notification
           # @param out [#puts] the server's output, where each notification is written

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

@@ -156,7 +156,8 @@ module Hecks
           with_progress(token) { tool_result(answer_tool(params["name"], params["arguments"] || {})) }
         end
 
-        # Runs the block with a progress seam for this call's stages, so their lines reach the client as
+        # Runs the block with a progress seam for this call's stages, so their lines reach the
+        # client as
         # notifications. The seam is per thread and removed when the call ends.
         # @param token [Object] the client's progress token
         # @return [Object] the block's value

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

@@ -13,7 +13,8 @@ module Hecks
           # Checks every argument in `args`, nested or not, and refuses the first one the policy
           # forbids.
           #
-          # Read-only questions whose `path` names one file of the checkout. `path` is denied by name
+          # Read-only questions whose `path` names one file of the checkout. `path` is denied by
+          # name
           # for every other command, since it can name a place to write; these reads are allowed it,
           # and admit_path! still confines it to the checkout.
           READ_PATH_QUESTIONS = %w[codebase.read_source codebase.outline].freeze

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

@@ -3,15 +3,19 @@ module Hecks
     module Driving
       module Ruby
         module AggregateModule
-          # The hooks an aggregate module lands on: a port declared inside a repeat boot, the bare and
-          # qualified binding calls a `.hecksagon` and a `.world` make, and constant lookup. Each is a
-          # module function, called as `Hooks.name` from the blocks that define the module's methods, since
+          # The hooks an aggregate module lands on: a port declared inside a repeat boot, the bare
+          # and
+          # qualified binding calls a `.hecksagon` and a `.world` make, and constant lookup. Each is
+          # a
+          # module function, called as `Hooks.name` from the blocks that define the module's
+          # methods, since
           # a block defined with `define_singleton_method` runs with the module as `self`.
           module Hooks
             # What `bound_outcome` answers for a call that is not a binding, so `super` handles it.
             UNBOUND = Object.new.freeze
 
-            # What `bound_outcome` answers for a call that recorded a binding, so the module answers itself.
+            # What `bound_outcome` answers for a call that recorded a binding, so the module answers
+            # itself.
             BOUND = Object.new.freeze
 
             module_function
@@ -59,7 +63,8 @@ module Hecks
               end
             end
 
-            # Defines `respond_to_missing?`, answering true while a `.hecksagon` or `.world` is being declared.
+            # Defines `respond_to_missing?`, answering true while a `.hecksagon` or `.world` is
+            # being declared.
             #
             # @param mod [Module] the aggregate module
             # @return [void]
@@ -70,8 +75,10 @@ module Hecks
               end
             end
 
-            # Defines `const_missing`. It uses `aggregate.hecks_name`, not the qualified name: qualifying it
-            # would make `Account::Debit`'s meaning depend on whether a stale module from an earlier boot is
+            # Defines `const_missing`. It uses `aggregate.hecks_name`, not the qualified name:
+            # qualifying it
+            # would make `Account::Debit`'s meaning depend on whether a stale module from an earlier
+            # boot is
             # still on this process.
             #
             # @param mod [Module] the aggregate module
@@ -86,8 +93,10 @@ module Hecks
               end
             end
 
-            # Declares a port on an aggregate during a repeat boot, and registers it with the live registry.
-            # Re-resolves the aggregate via `Hecks.current_registry` rather than the closed-over `aggregate`,
+            # Declares a port on an aggregate during a repeat boot, and registers it with the live
+            # registry.
+            # Re-resolves the aggregate via `Hecks.current_registry` rather than the closed-over
+            # `aggregate`,
             # which can be stale from an earlier boot.
             #
             # @raise [Bluebook::DSL::Malformed] when called outside a boot
@@ -96,8 +105,10 @@ module Hecks
               built = Bluebook::DSL::ConstShim.with(->(const) { const }) do
                 Bluebook::DSL::DomainPortBuilder.build(name, owner: current.hecks_name, &block)
               end
-              # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port` registers. It belongs to
-              # no aggregate IR, so it takes the registry's `add_port` directly. Mirrors `DSL::BindingProxy#port`,
+              # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port` registers. It
+              # belongs to
+              # no aggregate IR, so it takes the registry's `add_port` directly. Mirrors
+              # `DSL::BindingProxy#port`,
               # which handles the identical shape on a domain's first in-process boot.
               return Hecks.current_registry.add_port(built) if built.is_a?(Bluebook::Port)
 
@@ -112,14 +123,16 @@ module Hecks
                 raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
             end
 
-            # Points each reference attribute of a port's operations at the aggregate that declares it.
+            # Points each reference attribute of a port's operations at the aggregate that declares
+            # it.
             def reference_operations(built, current)
               built.operations.each do |operation|
                 operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = current }
               end
             end
 
-            # Answers what a method-missing call means: a bare call's attribute path, the world's record of
+            # Answers what a method-missing call means: a bare call's attribute path, the world's
+            # record of
             # a setting, a recorded binding (BOUND), or nothing to bind (UNBOUND).
             #
             # @return [Object] the answer, or BOUND or UNBOUND
@@ -137,7 +150,8 @@ module Hecks
               BOUND
             end
 
-            # @return [Boolean] whether the call names no arguments and no block, so it is a bare attribute path
+            # @return [Boolean] whether the call names no arguments and no block, so it is a bare
+            #   attribute path
             def bare_call?(args, kwargs, block)
               args.empty? && kwargs.empty? && !block
             end

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

@@ -21,7 +21,8 @@ module Hecks
           # find/all/count/events, project/docs/narrate, and the port/binding hooks.
           #
           # Each concern is a helper that defines its methods on the module and closes over the same
-          # arguments. The hooks live in `AggregateModule::Hooks`, which the module's blocks call by name.
+          # arguments. The hooks live in `AggregateModule::Hooks`, which the module's blocks call by
+          # name.
           def aggregate_module(dispatcher, domain, aggregate)
             fqn = "#{domain}::#{aggregate.hecks_name}"
             mod = Module.new
@@ -47,7 +48,8 @@ module Hecks
             end
           end
 
-          # The module's everyday surface: its commands, its identity, its projections, and its reads.
+          # The module's everyday surface: its commands, its identity, its projections, and its
+          # reads.
           def define_surface(mod, dispatcher, domain, aggregate, fqn)
             define_creating_commands(mod, dispatcher, domain, aggregate, fqn)
             define_reflection(mod, dispatcher, domain, aggregate, fqn)

data/lib/hecks/assembly.rb

@@ -13,6 +13,10 @@ module Hecks
     # means no overlay, whatever the variable holds.
     FROM_ENV = :from_env
 
+    # The variable that moves the Hecks world's event tap for a process no hecks command runs: a
+    # spec run sets it for itself and every child it starts.
+    EVENT_TAP_VARIABLE = "HECKS_EVENT_TAP".freeze
+
     module_function
 
     # The overlay a boot loads: the caller's own choice (nil meaning none), else the
@@ -28,6 +32,13 @@ module Hecks
       named.empty? ? nil : named
     end
 
+    # The event tap override a boot hands the runtime: `HECKS_EVENT_TAP` when it is set (a path
+    # moves the Hecks world's tap, an empty value switches it off), else nil, which leaves the
+    # world's tap where it is. A world that declares no tap ignores it.
+    #
+    # @return [String, nil] the override
+    def event_tap_override = ENV.fetch(EVENT_TAP_VARIABLE, nil)
+
     # Boots a domain directory. See `Runtime::Loader.boot`.
     #
     # @param path [String] path to a domain directory, or a file inside one
@@ -36,7 +47,8 @@ module Hecks
     # @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)),
+      drive(Runtime::Loader.boot(path, shared: shared, environment: selected_environment(environment),
+                                       event_tap: event_tap_override),
             install_driving)
     end
 
@@ -57,7 +69,7 @@ module Hecks
     # @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)
+      drive(Runtime::Loader.boot_described(described, event_tap: event_tap_override), install_driving)
     end
 
     # Boots exactly the named files. See `Runtime::Loader.boot_files`.
@@ -66,9 +78,11 @@ module Hecks
     # @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`
+    # @param adapters [Array<String>, nil] exactly the `.adapter` files to load; see the loader
     # @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)),
+    def boot_files(paths, shared: nil, install_driving: true, environment: FROM_ENV, adapters: nil)
+      drive(Runtime::Loader.boot_files(paths, shared: shared, environment: selected_environment(environment),
+                                              adapters: adapters, event_tap: event_tap_override),
             install_driving)
     end