hecks 4.0.0 → 6.0.0

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

@@ -8,26 +8,29 @@ module Hecks
         # `CliRunner`.
         module Answers
           # What a dispatch needs beyond the spec: the parsed arguments, whether `--wait` was given,
-          # and the chapter and launcher setting the command belongs to.
-          Invocation = Struct.new(:args, :wait, :bluebook, :launcher)
+          # and the bluebook and launcher setting the command belongs to.
+          Invocation = Struct.new(:args, :wait, :bluebook, :launcher, :text)
+
+          # The flag that asks for a command's recorded output as plain text and nothing else.
+          TEXT = "--text".freeze
 
           # Parses one resolved command's arguments, runs it as a query or command, and turns the
           # outcome, or the domain's refusal, into `[json_or_message, status]`. With `--wait`, a
           # question whose report names a gap (`LauncherOptions.gap_reported?`) answers status 1.
           #
-          # @param bluebook [Bluebook::Chapter] the chapter the command belongs to
-          # @param launcher [Hash, nil] the chapter's `launcher` world setting; nil when not opted
+          # @param bluebook [Bluebook::Declaration] the bluebook the command belongs to
+          # @param launcher [Hash, nil] the bluebook's `launcher` world setting; nil when not opted
           #   in
           def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil) # rubocop:disable Metrics/ParameterLists -- the signature is what `call` passes
-            args, wait = command_line(spec, rest, launcher)
+            args, wait, text = command_line(spec, rest, launcher)
             return answer_query(runtime, spec, args, wait, launcher) if spec[:kind] == :query
 
-            run_command(runtime, spec, Invocation.new(args, wait, bluebook, launcher))
+            run_command(runtime, spec, Invocation.new(args, wait, bluebook, launcher, text))
           rescue Runtime::NotFound, Runtime::TypeMismatch => e
             # A bad argument and a missing record both need the same next step: read the help.
             ["#{e.message}\n\n  #{program} #{"query " if asking}#{name} --help", 1]
           rescue *Runtime::DOMAIN_REFUSALS => e
-            # The refusal is the chapter's own sentence, verbatim.
+            # The refusal is the bluebook's own sentence, verbatim.
             [e.message, 1]
           rescue StandardError => e
             # So is a wrapped tool's, when a question's adapter refuses to answer.
@@ -36,17 +39,20 @@ module Hecks
             [e.message, 1]
           end
 
-          # The parsed arguments of a command line and whether to wait for the reactions.
+          # The parsed arguments of a command line, whether to wait for the reactions, and whether
+          # `--text` asked for the recorded output alone (which waits).
           def command_line(spec, rest, launcher)
-            rest, wait = LauncherOptions.take_wait(spec, rest) if launcher
-            [Cli.arguments(spec, rest), wait || LauncherOptions.settled?(launcher, spec)]
+            text = launcher ? rest.include?(TEXT) : false
+            rest, wait = LauncherOptions.take_wait(spec, rest - [TEXT]) if launcher
+            [Cli.arguments(spec, rest), text || wait || LauncherOptions.settled?(launcher, spec), text]
           end
 
           # Whether the error is a wrapped tool's refusal. Matched by name: the adapters belong to
           # the
-          # Hecks chapter, which a client's runtime never loads.
+          # Hecks bluebook, which a client's runtime never loads.
           def tool_refusal?(error)
-            error.class.ancestors.map(&:name).include?(CliRunner::TOOL_REFUSAL)
+            ancestor_names = error.class.ancestors.map(&:name)
+            ancestor_names.include?(CliRunner::TOOL_REFUSAL)
           end
 
           # Runs a command and answers its outcome, settled when `--wait` asks for it.
@@ -54,7 +60,9 @@ module Hecks
             args, minted = LauncherOptions.run_key(runtime, spec, invocation.args, invocation.launcher)
             handle = runtime.dispatch_flat(spec[:command], normalized_request(spec, args))
             extra  = refusals_and_run(handle, minted)
-            return settled(runtime, spec, handle, invocation.bluebook, invocation.launcher, extra) if invocation.wait
+            if invocation.wait
+              return settled(runtime, spec, handle, invocation.bluebook, invocation.launcher, extra, text: invocation.text)
+            end
 
             [JSON.pretty_generate(outcome(handle, extra)), 0]
           end
@@ -80,7 +88,7 @@ module Hecks
           # Runs a question and answers its rows, or its text when an adapter answered in text.
           #
           # @param wait [Boolean, nil] whether `--wait` was given: a report naming a gap then fails
-          # @param launcher [Hash, nil] the chapter's `launcher` setting, which may name the
+          # @param launcher [Hash, nil] the bluebook's `launcher` setting, which may name the
           #   questions that refuse a run they do not hold
           # @return [Array(String, Integer)] the answer and the status
           def answer_query(runtime, spec, args, wait, launcher = nil)
@@ -130,8 +138,7 @@ module Hecks
           # without this the answer would say nothing of it. A defect (a crash) is shown apart, as
           # `reaction_defects:`, and fails `--wait`.
           #
-          # @param handle [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
-          #   outcome
+          # @param handle [Runtime::Dispatcher::Result, Adapters::Lambda::RemoteDispatcher::Result]
           # @return [Hash] `refused_reactions:` each with the `policy`, its `trigger`, the `reason`;
           #   empty when every reaction was delivered (or a remote host sent no per-step log), plus
           #   `reaction_defects:` when one crashed

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

@@ -16,7 +16,7 @@ module Hecks
             refused = Admission.refusal(runtime.registry, "Cli")
             return { answer: [refused, 1] } if refused
 
-            bluebook, argv, program = chapter_for(runtime, argv, program)
+            bluebook, argv, program = bluebook_for(runtime, argv, program)
             launcher = LauncherOptions.settings(runtime, bluebook.name)
             options  = LauncherOptions.projection(launcher, program)
             cli = Projector.call(:cli, bluebook: bluebook, options: options.merge(audience(runtime, launcher)))
@@ -78,26 +78,27 @@ module Hecks
           end
 
           # What the help leaves out and points at for whoever typed the line: the maintainer's
-          # aggregates only in a hecks checkout, and the chapters the chapter's launcher names, each
+          # aggregates only in a hecks checkout, and the bluebooks the bluebook's launcher names,
+          # each
           # with the first sentence of what it is for.
           #
-          # @return [Hash{Symbol => Object}] `:hide` and `:chapters` (pairs of word and summary)
+          # @return [Hash{Symbol => Object}] `:hide` and `:bluebooks` (pairs of word and summary)
           def audience(runtime, launcher, maintainer: LauncherOptions.maintainer?,
                        newcomer: !maintainer && Newcomer.applies?)
             shown = (newcomer && Newcomer.audience(launcher)) || LauncherOptions.audience(launcher, maintainer)
-            return shown unless shown[:chapters]
+            return shown unless shown[:declarations]
 
-            shown.merge(chapters: chapter_summaries(runtime, shown[:chapters]))
+            shown.merge(declarations: bluebook_summaries(runtime, shown[:declarations]))
           end
 
-          # Each named chapter the domain attaches, as its word and the first sentence of its
+          # Each named bluebook the domain attaches, as its word and the first sentence of its
           # vision.
-          def chapter_summaries(runtime, names)
-            known = attached_chapters(runtime)
+          def bluebook_summaries(runtime, names)
+            known = attached_bluebooks(runtime)
             names.filter_map do |name|
               next unless known.include?(name)
 
-              [Naming.snake(name), Projector::CliProjector.first_sentence(runtime.registry.bluebook(name).vision)]
+              [Naming.snake(name), Projector::CliProjector.first_sentence(runtime.bluebook(name).vision)]
             end
           end
 
@@ -111,11 +112,11 @@ module Hecks
           # Reads the entry words of a line: whether it asks a query, the bare name, and the words
           # from the name on.
           #
-          # `query` gives queries their own namespace (`ask` is its older spelling); a chapter may
+          # `query` gives queries their own namespace (`ask` is its older spelling); a bluebook may
           # declare a command and a query of one name. A trailing `!` says the word is a command and
           # is not part of the name. A query answers to its bare name too; `query` is needed only
-          # when
-          # a command shares it.
+          # when a command shares it. The name may be written in the bluebook's verb form
+          # (`Hecks::PushTrain.board!`), which reaches the same command (see `VerbNames`).
           #
           # @return [Array(Boolean, String, Array<String>)] `asking`, `name` (nil when absent),
           #   `argv`
@@ -126,7 +127,7 @@ module Hecks
             return [asking, nil, argv] if name.nil?
 
             bang = name.end_with?("!")
-            name = name.chomp("!")
+            name = canonical_name(cli, name.chomp("!"))
             [asking || (!bang && query_only?(cli, name)), name, argv]
           end
 
@@ -135,21 +136,21 @@ module Hecks
             !cli[:names][:command].key?(name) && cli[:names][:question].key?(name)
           end
 
-          # The chapter a command line speaks to: the booted domain's own, or, when the first word
-          # names a chapter its hecksagon attaches or uses as a framework member (`deploy`,
-          # `governance`), that chapter, with the word dropped and added to the program name.
-          def chapter_for(runtime, argv, program)
-            own    = runtime.registry.bluebooks.values.first
-            target = attached_chapters(runtime).find { |name| Naming.snake(name) == argv.first }
+          # The bluebook a command line speaks to: the booted domain's own, or, when the first word
+          # names a bluebook its hecksagon attaches or uses as a framework member (`deploy`,
+          # `governance`), that bluebook, with the word dropped and added to the program name.
+          def bluebook_for(runtime, argv, program)
+            own    = runtime.first_bluebook
+            target = attached_bluebooks(runtime).find { |name| Naming.snake(name) == argv.first }
             return [own, argv, program] unless target
 
-            [runtime.registry.bluebook(target), argv[1..], "#{program} #{argv.first}"]
+            [runtime.bluebook(target), argv[1..], "#{program} #{argv.first}"]
           end
 
-          # The chapters the booted domain's hecksagon attaches or uses as framework members.
-          def attached_chapters(runtime)
-            own = runtime.registry.bluebooks.values.first
-            Array(runtime.registry.hecksagon(own.name)&.member_chapters)
+          # The bluebooks the booted domain's hecksagon attaches or uses as framework members.
+          def attached_bluebooks(runtime)
+            own = runtime.first_bluebook
+            Array(runtime.hecksagon(own.name)&.member_bluebooks)
           end
         end
       end

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

@@ -6,6 +6,9 @@ module Hecks
       module CliRunner
         # The answer `--wait` gives once every reaction has run. Extended into `CliRunner`.
         module Settling
+          # The `Some::ErrorClass: ` an adapter's failure text opens with.
+          QUALIFIED_CLASS_PREFIX = /\A(\w+::)+\w+: /
+
           # The answer `--wait` gives: the record re-read after every reaction has run, with all its
           # events, and a status of 1 when its lifecycle ended in a failure state, a refused
           # reaction
@@ -18,7 +21,7 @@ module Hecks
           #
           # @return [Array(String, Integer)] the JSON and the status, plus (Array(String, Integer,
           #   String)) why the run failed when it did
-          def settled(runtime, spec, handle, bluebook, launcher, extra) # rubocop:disable Metrics/ParameterLists -- pinned by the callers and specs
+          def settled(runtime, spec, handle, bluebook, launcher, extra, text: false) # rubocop:disable Metrics/ParameterLists -- pinned by the callers and specs
             why = reactions_failed(handle)
             return finish(stateless_json(handle, extra), why) if handle.state.nil?
 
@@ -26,7 +29,7 @@ module Hecks
             state     = reread(runtime, bluebook, aggregate, handle) || handle.state
             answer    = settled_answer(handle, state, settled_event_names(runtime, bluebook, aggregate, handle), extra)
             why      += failure_reasons(aggregate, state, launcher)
-            settled_result(answer, LauncherOptions.report?(launcher, spec), why)
+            settled_result(answer, text || LauncherOptions.report?(launcher, spec), why)
           end
 
           # The settled answer as the launcher's report when it prints one, else as JSON.
@@ -55,7 +58,7 @@ module Hecks
           def failure_reasons(aggregate, state, launcher)
             return [] unless LauncherOptions.failed?(aggregate, state, launcher)
 
-            [failure_sentence(aggregate, state, aggregate.lifecycle.field)]
+            [failure_sentence(aggregate, state, aggregate.lifecycle_field)]
           end
 
           # The answer of a command the launcher prints as its report: the text it recorded, with
@@ -77,7 +80,7 @@ module Hecks
             refusal  = refusal[:value] if refusal.is_a?(Hash)
             return sentence if refusal.to_s.strip.empty?
 
-            "#{sentence}: #{refusal.to_s.strip.sub(/\A(\w+::)+\w+: /, "")}"
+            "#{sentence}: #{refusal.to_s.strip.sub(QUALIFIED_CLASS_PREFIX, "")}"
           end
 
           # The answer and its status: 0 when nothing failed, else 1 with the reasons joined.
@@ -111,7 +114,8 @@ module Hecks
           def reread(runtime, bluebook, aggregate, handle)
             return unless aggregate && runtime.respond_to?(:registry)
 
-            runtime.registry.repository(bluebook.name, aggregate)&.find(handle.id)&.to_h
+            repository = runtime.repository(bluebook.name, aggregate)
+            repository&.find(handle.id)&.to_h
           end
         end
       end

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

@@ -12,7 +12,7 @@ module Hecks
           # setting lists under `streams`, given `--stream`; `from_now` applies to the first ask
           # only.
           #
-          # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+          # @param runtime [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the domain
           # @param argv [Array<String>] as for `call`, with `--stream`
           # @param program [String] how the caller was invoked
           # @param out [IO] where each entry's line goes

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

@@ -2,19 +2,28 @@ module Hecks
   module Adapters
     module Driving
       module CliRunner
-        # Words the answer for a command or question the chapter does not declare. Extended into
+        # Words the answer for a command or question the bluebook does not declare. Extended into
         # `CliRunner`.
         module Suggestions
           # Words the answer for an unknown command or question, suggesting up to five near names.
           # Ranked by shared prefix, which survives a dropped letter where a substring would not.
           def unknown(cli, name, asking, program)
-            near  = near_names(cli, name, asking)
+            near  = near_names(cli, snake_form(name), asking)
             lines = ["no such #{asking ? "query" : "command"}: #{name}"]
-            lines += ["", "did you mean:", *near.first(5).map { |candidate| "  #{candidate}" }] unless near.empty?
+            shown = near.first(5).map { |candidate| "  #{shown_name(cli, candidate, asking)}" }
+            lines += ["", "did you mean:", *shown] unless near.empty?
             lines += ["", "  #{program}#{" query" if asking}   for the full list"]
             lines.join("\n")
           end
 
+          # A suggested name as the listing prints it, in the bluebook's verb form. A candidate from
+          # the other namespace (a bare name's home) is printed as it is.
+          def shown_name(cli, candidate, asking)
+            specs = asking ? cli[:questions] : cli[:commands]
+            spec  = specs[cli[:names][asking ? :question : :command][candidate]]
+            spec ? Projector::CliProjector.verb_form(spec, candidate) : candidate
+          end
+
           # The names worth suggesting: the bare name's homes first, then the names sharing a
           # prefix.
           def near_names(cli, name, asking)
@@ -29,10 +38,9 @@ module Hecks
 
           # The pool's names that share at least half of `name` (and three letters) as a prefix.
           def similar_names(pool, name)
-            pool.map { |candidate| [shared_prefix(candidate, name), candidate] }
-                .select { |shared, _| shared >= [name.length / 2, 3].max }
-                .sort_by { |shared, candidate| [-shared, candidate] }
-                .map(&:last)
+            scored = pool.map { |candidate| [shared_prefix(candidate, name), candidate] }
+            close = scored.select { |shared, _| shared >= [name.length / 2, 3].max }
+            close.sort_by { |shared, candidate| [-shared, candidate] }.map(&:last)
           end
 
           # The length of the prefix two words share.

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

@@ -0,0 +1,49 @@
+module Hecks
+  module Adapters
+    module Driving
+      module CliRunner
+        # Reads the spellings a line may give a command or query. The launcher indexes them by the
+        # snake-case `aggregate.verb` the projection prints; the bluebook's own verb form, such as
+        # `Hecks::PushTrain.Board`, reaches the same one. Extended into `CliRunner`.
+        module VerbNames
+          # A realm written before the aggregate: `Hecks::`.
+          REALM = /\A(?:[A-Z]\w*::)+/
+
+          # The name the projection indexes a typed name under: the name itself when it is one,
+          # else its verb form read into snake case, else the name as typed, for the refusal to
+          # name.
+          #
+          # @param cli [Hash] the projection, holding the `:names` it indexes
+          # @param typed [String] the word typed, without its `!`
+          # @return [String] the indexed name, or `typed` when none matches
+          def canonical_name(cli, typed)
+            [typed, *verb_form_names(typed)].find { |name| indexed?(cli, name) } || typed
+          end
+
+          # A typed name as the projection spells it, to match what was typed against the names it
+          # indexes: `Hecks::PushTrain.bord` as `push_train.bord`.
+          #
+          # @param typed [String] the word typed, without its `!`
+          # @return [String] the realm dropped and each dotted segment in snake case
+          def snake_form(typed) = snake_segments(typed).join(".")
+
+          private
+
+          # `Hecks::PushTrain.board` as `push_train.board`; a verb that names an entity's command,
+          # `PushTrain.Launcher.Refresh`, also as `push_train.refresh`, the way the projection
+          # exposes it.
+          def verb_form_names(typed)
+            segments = snake_segments(typed)
+            [segments.join("."), [segments.first, segments.last].join(".")].uniq
+          end
+
+          def snake_segments(typed) = typed.sub(REALM, "").split(".").map { |segment| Naming.snake(segment) }
+
+          def indexed?(cli, name)
+            cli[:names][:command].key?(name) || cli[:names][:question].key?(name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -11,6 +11,7 @@ require_relative "cli_runner/resolution"
 require_relative "cli_runner/settling"
 require_relative "cli_runner/streaming"
 require_relative "cli_runner/suggestions"
+require_relative "cli_runner/verb_names"
 
 module Hecks
   module Adapters
@@ -25,6 +26,7 @@ module Hecks
 
         extend Resolution
         extend Suggestions
+        extend VerbNames
         extend Answers
         extend Settling
         extend Streaming
@@ -32,9 +34,9 @@ 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

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.
@@ -83,20 +86,19 @@ module Hecks
         #   with Symbol keys; a leaf is returned as it came
         def deep_symbolize(value) = Runtime::Value.deep_symbolize(value)
 
-        # Unwraps a record, a query row, or any value holding `Runtime::Value`s into plain
-        # Hashes, Arrays and scalars a JSON encoder can walk.
-        #
-        # Delegates to `Runtime::Value.materialize`; the only addition is `#to_h` on a
-        # `Handle`, which `materialize` does not recognize.
+        # Unwraps a record, a query row, or any value holding `Runtime::Value`s into the plain
+        # data a caller is answered with. A single-field value object answers as its bare
+        # field (`name: "Margherita"`), the shape a command takes it in; stored state stays
+        # wrapped.
         #
         # @param value [Adapters::Driving::Handle, Runtime::Value, Hash, Array, Object] what to
-        #   unwrap;
-        #   a `Handle` is read through its `to_h`, so its `:id` comes along
+        #   unwrap; a `Handle` is read through its `to_h`, so its `:id` comes along
         # @return [Hash, Array, Object] the same data with every `Runtime::Value` replaced
-        #   by a Hash of its fields; any other value is returned as it came
+        #   by its sole field's value, or by a Hash of its fields when it has more than one;
+        #   any other value is returned as it came
         def materialize(value)
           value = value.to_h if value.is_a?(Handle)
-          Runtime::Value.materialize(value)
+          Runtime::Value.materialize_unwrapped(value)
         end
 
         # Turns a command's JSON body, raw or already parsed, into the `to:`/`with:`