hecks 5.0.0 → 7.0.0

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

@@ -1,6 +1,9 @@
 require "json"
 require_relative "cli"
 require_relative "command_request"
+require_relative "context_line"
+require_relative "exit_status"
+require_relative "write_guard"
 require_relative "json"
 require_relative "launcher_options"
 require_relative "newcomer"
@@ -8,23 +11,45 @@ require_relative "../../projector"
 require_relative "../../ports/clock"
 require_relative "cli_runner/answers"
 require_relative "cli_runner/resolution"
+require_relative "cli_runner/run_replay"
+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/json_words"
 require_relative "cli_runner/settling"
 require_relative "cli_runner/streaming"
 require_relative "cli_runner/suggestions"
+require_relative "cli_runner/verb_names"
+require_relative "cli_runner/renamed_names"
+require_relative "cli_runner/verbosity"
+require_relative "cli_runner/name_index"
 
 module Hecks
   module Adapters
     module Driving
       # Parses and dispatches a command line against a `Projector::CliProjector` projection.
-      # Does no IO: it answers `[text, status]` and leaves printing and exiting to its callers.
+      # Does no IO: it answers `[text, status]` (an `ExitStatus`) and leaves printing and exiting
+      # to its callers.
       module CliRunner
+        include ExitStatus
+        extend Verbosity
+
         # The class an adapter raises when the tool it wraps refuses.
         TOOL_REFUSAL = "Hecks::Adapters::ConsoleCapture::Failure".freeze
         # The words that open the query namespace; `ask` is the older spelling.
         QUERY_WORDS = %w[query ask].freeze
 
         extend Resolution
+        extend SearchWords
+        extend CompletionWords
+        extend TourWords
+        extend ResumeWords
+        extend JsonWords
         extend Suggestions
+        extend NameIndex
+        extend VerbNames
+        extend RenamedNames
         extend Answers
         extend Settling
         extend Streaming
@@ -32,22 +57,95 @@ module Hecks
         module_function
 
         # Runs one command line against a booted domain and answers the text to print.
-        # The booted domain's own chapter is projected, or an attached one its first word names.
+        # The booted domain's own bluebook is projected, or an attached one its first word names.
         #
-        # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+        # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted domain
         # @param argv [Array<String>] an optional `query` (or `ask`), the command or query name,
-        #   then
-        #   `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
+        #   then `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
         # @param program [String] how the caller was invoked, echoed in usage and hints
-        # @return [Array(String, Integer)] the text and the status: 0 answered, 1 refused or misused
+        # @return [Array(String, Integer)] the text and the `ExitStatus`: `ANSWERED`, `REFUSED`
+        #   when the domain said no or the run failed, `USAGE` when the line could not be read
         # @raise [Runtime::WiringError] if a repository or the clock adapter cannot be resolved
         # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every retry
-        def call(runtime:, argv:, program: "hecks run")
+        def call(runtime:, argv:, program: "hecks run", usage_log: false, err: $stderr)
+          level, argv = split_verbosity(argv)
+          return [Verbosity::CONFLICT, USAGE] if level == :conflict
+          return if argv.first == "resume" && argv[1] # a resume that names a run runs a saga: it needs a booted domain
+
+          with_verbosity(level) { answer_line(runtime, argv, program, usage_log, err) }
+        rescue Interrupt
+          [interrupted(argv), ExitStatus::REFUSED]
+        end
+
+        # Answers one line: resolves it, guards a write, dispatches it and records its usage.
+        #
+        # @api private
+        # @return [Array(String, Integer)] the text and the `ExitStatus`
+        def answer_line(runtime, argv, program, usage_log, err)
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           plan = resolve(runtime, argv, program)
           return plan[:answer] if plan[:answer]
 
-          dispatch(runtime, plan[:spec], plan[:name], plan[:rest], plan[:program], plan[:asking],
-                   bluebook: plan[:bluebook], launcher: plan[:launcher])
+          refused = guard_command(plan, err)
+          return [refused, ExitStatus::REFUSED] if refused
+
+          answer = dispatch(runtime, plan[:spec], plan[:name], plan[:rest], plan[:program], plan[:asking],
+                            bluebook: plan[:bluebook], launcher: plan[:launcher])
+          finish_line(answer, plan, started, { argv: argv, usage_log: usage_log, err: err })
+        end
+
+        # Records a line that ran and prints its details when `-v` asked for them.
+        #
+        # @api private
+        # @return [Array(String, Integer)] the answer, unchanged
+        def finish_line(answer, plan, started, details)
+          UsageLog.record(argv: details[:argv], resolved: plan[:name], status: answer[1], started: started) if details[:usage_log]
+          verbose_details(details[:err], plan[:name], started) if verbose?
+          answer
+        end
+
+        # The line an interrupted command ends with: what it was and that it was not finished,
+        # so the caller sees a refusal rather than a bare stop.
+        #
+        # @api private
+        # @return [String] the text the caller prints on standard error
+        def interrupted(argv)
+          name = argv.first || "the command"
+          "interrupted during #{name}: the run was stopped before it finished"
+        end
+
+        # Before a command (not a query) runs: refuses a write that would land in Memory from a
+        # worktree whose main checkout stores it elsewhere, else prints the context line.
+        #
+        # @api private
+        # @return [String, nil] the refusal, or nil when the command may run
+        def guard_command(plan, err)
+          return if plan[:asking]
+
+          refusal = WriteGuard.refusal(Dir.pwd, plan[:bluebook]&.name)
+          return refusal if refusal
+
+          ContextLine.announce(err) unless quiet?
+          nil
+        end
+
+        # The names a person can type at the launcher, as the projection names them: commands and
+        # queries, leaving out the internal steps a run records about itself.
+        #
+        # @param runtime [#registry] a booted domain, or what `Hecks.describe` answers
+        # @param program [String] how the caller was invoked
+        # @return [Array<String>] the sorted names
+        def known_names(runtime:, program: "hecks run")
+          bluebook, = bluebook_for(runtime, [], program)
+          launcher = LauncherOptions.settings(runtime, bluebook.name)
+          options = LauncherOptions.projection(launcher, program)
+          cli = Projector.call(:cli, bluebook: bluebook, options: options.merge(audience(runtime, launcher)))
+          public_names(cli[:names][:command], cli[:commands]) + public_names(cli[:names][:question], cli[:questions])
+        end
+
+        # @return [Array<String>] the names whose spec is not internal
+        def public_names(names, specs)
+          names.reject { |_, id| specs.dig(id, :internal) }.keys.sort
         end
 
         # Answers a command line that asks only for usage, from the projection alone.
@@ -62,6 +160,9 @@ module Hecks
         # @return [Array(String, Integer), nil] the text and status, or nil when the line would
         #   run a command or question and so needs a booted domain
         def usage(runtime:, argv:, program: "hecks run")
+          level, argv = split_verbosity(argv)
+          return [Verbosity::CONFLICT, USAGE] if level == :conflict
+
           UsageCache.fetch(runtime, argv, program, audience: audience_key) { resolve(runtime, argv, program)[:answer] }
         end
       end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "launcher_options"
+
+module Hecks
+  module Adapters
+    module Driving
+      # The one line a command prints before it writes: which checkout it runs in, the store each
+      # bluebook uses, and the audience the launcher lists for. It reads only, through the store
+      # resolution `hecks config` uses, so the line cannot disagree with a boot.
+      module ContextLine
+        MEMORY = "Memory"
+
+        # The store of a bluebook, as a label with no aggregate in it.
+        BLUEBOOK_STORE = /\Astore [^:]+\z/
+
+        # The storage kinds a store description starts with.
+        SQLITE_STORE = /\ASqlite/i
+        POSTGRES_STORE = /\APostgres/
+
+        module_function
+
+        # Prints the line on a terminal; a pipe or a file gets nothing, so stdout stays clean.
+        #
+        # @param err [#tty?, #puts] where the line goes
+        # @param directory [String] the checkout a command runs in
+        # @return [String, nil] the line printed, or nil when nothing was printed
+        def announce(err, directory: Dir.pwd)
+          return unless err.respond_to?(:tty?) && err.tty?
+
+          require_relative "../../hecks/adapters/settings_reading"
+
+          text = line(directory: directory, stores: SettingsReading.new.stores(directory),
+                      audience: audience(directory))
+          err.puts(text)
+          text
+        end
+
+        # @param directory [String] the checkout a command runs in
+        # @param stores [Array<Array(String, String, String)>] store rows, as `stores` answers them
+        # @param audience [String] the audience the launcher lists for
+        # @return [String] the line
+        def line(directory:, stores:, audience:)
+          ["checkout #{File.basename(directory)} (#{branch(directory)})", stored(stores),
+           "audience #{audience}"].join(" · ")
+        end
+
+        # @param stores [Array<Array(String, String, String)>] store rows
+        # @return [String] "Tickets in SQLite" for each bluebook off Memory, else Memory
+        def stored(stores)
+          found = stores.filter_map do |label, value, _source|
+            next unless label.match?(BLUEBOOK_STORE) && kind(value) != MEMORY
+
+            "#{label.delete_prefix("store ")} in #{kind(value)}"
+          end
+          found.empty? ? MEMORY : found.join(", ")
+        end
+
+        # @param value [String] a store's description, as the rows give it
+        # @return [String] the store's kind
+        def kind(value)
+          case value.to_s
+          when SQLITE_STORE then "SQLite"
+          when POSTGRES_STORE then "Postgres"
+          else value.to_s.split.first || MEMORY
+          end
+        end
+
+        # @param directory [String]
+        # @return [String] the checked-out branch, or "detached" when there is none
+        def branch(directory)
+          out, status = Open3.capture2e("git", "-C", directory, "symbolic-ref", "--short", "HEAD")
+          status.success? ? out.strip : "detached"
+        end
+
+        # @param directory [String]
+        # @return [String] "maintainer" inside a hecks checkout, else "person"
+        def audience(directory)
+          LauncherOptions.maintainer?(directory) ? "maintainer" : "person"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Hecks
+  module Adapters
+    module Driving
+      # The statuses a launcher exits with, which a script branches on: `CliRunner` answers them
+      # beside its text, the runner returns them, and every generated launcher passes them to
+      # `exit`. Three suffice: the line was answered, the domain said no, or the line could not
+      # be read. A crash and a domain that cannot be opened both end as `REFUSED`, because the
+      # launcher distinguishes neither from a refusal.
+      module ExitStatus
+        # The line ran and was answered: a usage, a command's outcome, a query's rows, a stream
+        # that ended, and a port operation's refusal event, which is an answer.
+        ANSWERED = 0
+
+        # The domain said no, or the run failed: a refusal, a record that is not there, a
+        # `--wait` run that ended in a failure state or whose reaction was refused or crashed, a
+        # question that reports a gap under `--wait`, the door refusing the caller, or a domain
+        # that cannot be opened.
+        REFUSED = 1
+
+        # The line could not be read: no command named, a command or query the bluebook does not
+        # declare, a word the command does not take, a value its type cannot hold, or a flag the
+        # command lacks.
+        USAGE = 2
+
+        # One line a launcher's help prints, naming the three statuses.
+        HELP_LINE = "exit status: #{ANSWERED} answered, #{REFUSED} refused or failed, " \
+                    "#{USAGE} a line it could not read".freeze
+      end
+    end
+  end
+end

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

@@ -40,7 +40,8 @@ module Hecks
           request = Rack::Request.new(env)
           return respond(405, error: "MethodNotAllowed", message: "POST only") unless request.post?
 
-          body = request.body.read
+          stream = request.body
+          body = stream.read
           verify_signature!(request, body)
           route(request.get_header(EVENT_HEADER), body)
         rescue InvalidSignature => e

data/lib/hecks/adapters/driving/handle/verb_methods.rb

@@ -0,0 +1,46 @@
+require_relative "../../../naming"
+
+module Hecks
+  module Adapters
+    module Driving
+      class Handle
+        # The two names each non-creating verb gets on a handle (ADR 0120): `name!` dispatches
+        # and `name` answers the verb's IR command. Both are real singleton methods, not
+        # method_missing, so a verb named `freeze` or `send` (Account::Freeze,
+        # ExternalTransfer::Send) wins over the Kernel method instead of silently hitting it.
+        module VerbMethods
+          # Object methods a bare verb name never replaces: identity, introspection and
+          # copying, which Ruby itself, `Hash` and test doubles call on any object.
+          CORE_NAMES = %i[__send__ __id__ object_id class singleton_class hash equal? eql? == is_a?
+                          kind_of? instance_of? respond_to? respond_to_missing? method_missing method
+                          public_send instance_variable_get instance_variable_set instance_variables
+                          define_singleton_method nil? dup clone itself tap then inspect to_s].freeze
+
+          # The names a bare verb leaves alone: every method a handle defines, plus `CORE_NAMES`.
+          #
+          # @return [Array<Symbol>] the reserved method names
+          def self.reserved_names
+            @reserved_names ||= (Handle.instance_methods(false) + Handle.private_instance_methods(false) +
+                                 private_instance_methods(false) + CORE_NAMES).uniq.freeze
+          end
+
+          private
+
+          def define_verb_methods
+            @ir.commands.reject(&:creates?).each do |command|
+              name = Naming.snake(command.hecks_name)
+              define_singleton_method("#{name}!") { |**args| run(command, **args) }
+              define_singleton_method(name) { command } unless keeps_its_name?(name.to_sym)
+            end
+          end
+
+          # A field reader, a method of the handle's own, or an Object method Ruby's machinery
+          # calls keeps its name; the verb's bang form still dispatches.
+          def keeps_its_name?(name)
+            @state.key?(name) || reader?(name) || VerbMethods.reserved_names.include?(name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 require_relative "../../naming"
 require_relative "../../runtime/caller"
 require_relative "../../ports/authorization"
+require_relative "handle/verb_methods"
 
 module Hecks
   module Adapters
@@ -10,11 +11,13 @@ module Hecks
       #
       #     Pizza.create_pizza!(...).add_topping!(...).purchase!(...)
       class Handle
+        include VerbMethods
+
         attr_reader :id
 
-        # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+        # @param dispatcher [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted
         #   dispatcher this record's verbs, `events` and `reload` go through
-        # @param domain [String] the owning chapter's name, the first half of `fqn`
+        # @param domain [String] the owning bluebook's name, the first half of `fqn`
         # @param aggregate [Bluebook::Aggregate] the IR of the aggregate this record is one of
         # @param instance [Runtime::Instance] the stored record; its `id` and `state` are
         #   read once here and the instance itself is not retained
@@ -157,18 +160,7 @@ module Hecks
         end
 
         def reader?(name)
-          !@ir.attribute(name).nil? || @ir.lifecycle&.field&.to_sym == name
-        end
-
-        # Real singleton methods, not method_missing: a verb named `freeze` or
-        # `send` (both real, e.g. Account::Freeze, ExternalTransfer::Send) would
-        # otherwise silently hit the Kernel method instead of dispatching.
-        def define_verb_methods
-          @ir.commands.reject(&:creates?).each do |command|
-            define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
-              run(command, **args)
-            end
-          end
+          !@ir.attribute(name).nil? || @ir.lifecycle_field&.to_sym == name
         end
 
         # `@ir.identified_by` is only the single-head shorthand (nil for a
@@ -183,8 +175,8 @@ module Hecks
         # when called; nothing loads until then, so chains like
         # `payment.disputed_by_customer.name` stay lazy at every step.
         #
-        # Defined before verb methods so a same-named verb wins the name on the
-        # rare collision; `initialize` calls this first for that reason.
+        # A verb of the same name leaves the accessor alone (`keeps_its_name?`); only the
+        # verb's bang form is defined.
         #
         # The accessor is named like the attribute itself, never `<name>_id`
         # (ADR 0025) — `piece.account` and `piece[:account]` (bracket access,
@@ -195,7 +187,7 @@ module Hecks
 
         # One lazy reader for a reference attribute.
         def define_reference_accessor(attribute)
-          target = attribute.type.resolve
+          target = attribute.target_aggregate
           # Cross-domain, or otherwise unresolvable — no accessor rather than a guess.
           return unless target
 

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

@@ -19,11 +19,11 @@ module Hecks
         # The name is checked against the current boot's IR before Ruby's constant table, so
         # a stale same-named constant from an earlier boot is never returned.
         #
-        # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
-        # @param domain [String, Symbol] the chapter name, such as `"Banking"`
+        # @param dispatcher [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the boot
+        # @param domain [String, Symbol] the bluebook name, such as `"Banking"`
         # @param name [String, Symbol] the aggregate's declared name, such as `"Customer"`
         # @return [Module] the aggregate module installed at `domain::name`
-        # @raise [Runtime::NotFound] if the chapter or its aggregate is not declared
+        # @raise [Runtime::NotFound] if the bluebook or its aggregate is not declared
         # @raise [NameError] if the aggregate has no facade constant (`install_driving: false`)
         def aggregate(dispatcher, domain, name)
           Admission.admit!(dispatcher.registry, "Json")
@@ -40,8 +40,9 @@ module Hecks
         # @return [String] the method name to `public_send` to the module
         # @raise [Runtime::NotFound] if the aggregate declares no creating command
         def creating_command(klass)
-          creating = klass.ir.commands.find(&:creates?)
-          raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no creating command" unless creating
+          ir = klass.ir
+          creating = ir.commands.find(&:creates?)
+          raise Runtime::NotFound, "#{ir.hecks_name} declares no creating command" unless creating
 
           "#{Naming.snake(creating.hecks_name)}!"
         end
@@ -59,10 +60,11 @@ module Hecks
         # @raise [Runtime::NotFound] if no non-creating command has that method name
         def validate_command!(klass, name)
           wanted = name.to_s
-          dispatchable = klass.ir.commands.reject(&:creates?).map { |command| "#{Naming.snake(command.hecks_name)}!" }
+          ir = klass.ir
+          dispatchable = ir.commands.reject(&:creates?).map { |command| "#{Naming.snake(command.hecks_name)}!" }
           return wanted if dispatchable.include?(wanted)
 
-          raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no command named #{wanted.inspect}"
+          raise Runtime::NotFound, "#{ir.hecks_name} declares no command named #{wanted.inspect}"
         end
 
         # Fetches one record by id, raising instead of answering nil on a miss.
@@ -72,7 +74,8 @@ module Hecks
         # @return [Adapters::Driving::Handle] the record in hand
         # @raise [Runtime::NotFound] if the repository holds no record with that id
         def find!(klass, id)
-          klass.find(id) or raise Runtime::NotFound, "no #{klass.ir.hecks_name} found for id #{id.inspect}"
+          ir = klass.ir
+          klass.find(id) or raise Runtime::NotFound, "no #{ir.hecks_name} found for id #{id.inspect}"
         end
 
         # Converts every Hash key to a Symbol, at every depth of a parsed JSON body.

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,26 +40,26 @@ 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)
-          { program: program, names: settings && settings[:names], mint_run_keys: settings && settings[:run_keys] }
+          { program:, opted: !settings.nil?, **settings.to_h.slice(:names, :renamed), mint_run_keys: settings&.dig(:run_keys) }
         end
 
         # Whether the person is working on a hecks checkout: `dir` or a directory above it holds
@@ -73,24 +78,26 @@ 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
-        # gets neither.
+        # shown only in a hecks checkout or to `--maintainer`) and the bluebooks pointed at
+        # (`bluebooks`, plus `maintainer_bluebooks` in a checkout), and the commands listed first
+        # (`everyday`). A bluebook that did not opt in gets none of them.
         #
-        # @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`, `:bluebooks` and `:everyday` (empty when the
+        #   setting names none), 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),
+            everyday: Array(settings[:everyday]).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 +149,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 +161,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 +172,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 +181,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 +222,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 +231,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 +243,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 +260,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)