hecks 1.3.0 → 1.4.0

data/lib/hecks/doc/reference.rb

@@ -6,7 +6,7 @@ module Hecks
     # The DSL reference, projected from the language's own Syntax chapter
     # — the same Keyword/Argument rows the conformance specs hold equal
     # to the live builders. Nothing here is described twice: the tables
-    # come from the declaration, the PROSE is hand-written between
+    # come from the declaration, the prose is hand-written between
     # markers the generator preserves, and the golden spec refuses a
     # tree where the two have drifted.
     #
@@ -19,9 +19,9 @@ module Hecks
       GENERATED_END = "<!-- generated:end -->".freeze
       TODO_SENTINEL = "<!-- TODO: document this word -->".freeze
 
-      # A PAGE'S OWN HAND-WRITTEN OPENING, harvested under a key no word
+      # A PAGE'S own hand-written opening, harvested under a key no word
       # can ever collide with (words are strings off the Syntax chapter;
-      # this is a Symbol). It exists so a page can boot ONCE — load a real
+      # this is a Symbol). It exists so a page can boot once — load a real
       # corpus chapter, wire its hexagon — and have every word's example
       # below run against that single boot, the way a guide's opening
       # `ruby boot` block already does. Without it each word would have to
@@ -33,7 +33,7 @@ module Hecks
 
       def generated_begin(word) = "<!-- generated:begin word=#{word} -->"
 
-      # Keyed by REGION rather than by word — the same marker convention,
+      # Keyed by region rather than by word — the same marker convention,
       # used for the parts of a page that are not about one word: a
       # page's generated lede here, README's generated indexes below.
       def region_begin(id) = "<!-- generated:begin id=#{id} -->"
@@ -56,7 +56,7 @@ module Hecks
       # same shape `rows` used to produce — nothing below this needed to
       # change.
       #
-      # NO SEPARATE `@keywords ||=` HERE ANYMORE. This module used to
+      # No separate `@keywords ||=` here anymore. This module used to
       # memoize its own copy on top of `SyntaxBoot.call`'s own memo — a
       # double cache with no way to invalidate either half, and a real
       # bug: whichever call in the whole process happened to land first
@@ -86,9 +86,9 @@ module Hecks
         end.merge("index.md" => render_index)
       end
 
-      # A WORD ADMITTING TWO FORMS HAS TWO ROWS — syntax.bluebook's own
+      # A WORD admitting two forms has two rows — syntax.bluebook's own
       # stated rule, and `identified_by` (a block, or a bare argument and
-      # none) is the case that made it real again. One SECTION per word all
+      # none) is the case that made it real again. One section per word all
       # the same: the prose is the word's rather than the form's, and the
       # argument rows join by (word, context) and so already cover every
       # form. Grouped rather than rendered per row, or a reader would meet
@@ -128,7 +128,7 @@ module Hecks
         inside.empty? ? "Words available in the #{context} body." : "Words available inside #{inside}."
       end
 
-      # One SPELLING per form, everything else off the first row — the
+      # One spelling per form, everything else off the first row — the
       # columns that differ between two forms of one word are `body` (which
       # is what the spelling shows) and nothing else.
       def render_word(forms, prose)
@@ -212,7 +212,7 @@ module Hecks
       # preamble is invented — the older shape reads back unchanged.
       # A single-pass line-scanning state machine (current/collecting/
       # buffer/in_fence) — each branch mutates shared local state that
-      # carries into the NEXT iteration, so splitting per branch would
+      # carries into the next iteration, so splitting per branch would
       # mean passing all four back and forth by reference every line.
       # rubocop:disable-next Metrics/PerceivedComplexity
       def harvest(text)
@@ -221,7 +221,7 @@ module Hecks
         collecting = false
         buffer = []
 
-        # A HEADING INSIDE A FENCE IS NOT A HEADING. `## something` is an
+        # A heading inside a fence is not a heading. `## something` is an
         # ordinary Ruby comment, and now that every word's section carries
         # runnable code, one written at the left margin would otherwise
         # end that section mid-example and orphan the rest of it under a
@@ -293,11 +293,11 @@ module Hecks
         lines.join("\n")
       end
 
-      # The opening comment PARAGRAPH, not just the first line — a table
+      # The opening comment paragraph, not just the first line — a table
       # cell that trails off mid-clause reads worse than one that runs a
       # little long and says "...". A code-bearing comment (`field.name`,
       # `pattern:`) makes naive sentence-splitting on "." or ":" cut in
-      # the wrong place, so this truncates on LENGTH alone.
+      # the wrong place, so this truncates on length alone.
       def tool_summary(path)
         comment_lines = []
         started = false
@@ -317,13 +317,13 @@ module Hecks
         text.length > 140 ? "#{text[0, 137]}..." : text
       end
 
-      # ONE REAL, COMMITTED FILE, READ FRESH — not re-derived from a boot
+      # One real, committed file, read fresh — not re-derived from a boot
       # (this module never requires `hecks/projections/diagrams`, and
       # shouldn't just to draw one example). `docs/generated/diagrams/`
       # is already held to the declaration by `spec/diagrams_spec.rb`'s
       # own drift check; this just quotes its own output, so the two
       # can't independently drift from each other either — a stale
-      # Order_lifecycle.mmd fails THAT spec long before this one runs.
+      # Order_lifecycle.mmd fails that spec long before this one runs.
       def diagram_showcase(root)
         lifecycle = File.read(File.join(root, "docs/generated/diagrams/pizzas/Order_lifecycle.mmd")).strip
         <<~MARKDOWN.strip
@@ -363,7 +363,7 @@ module Hecks
         File.write(path, render_readme(root, File.read(path)))
       end
 
-      # An example A READER CAN SEE and the harness will actually run.
+      # An example a reader can see and the harness will actually run.
       # `ruby skip` is display-only by the doctest harness's own rule, and
       # a hidden `<!-- doctest:boot -->` block is setup rather than an
       # example — a word whose only "example" is invisible or inert is a
@@ -373,7 +373,7 @@ module Hecks
 
       def exemplified?(prose) = prose.to_s.match?(EXAMPLE_FENCE)
 
-      # EVERY LIVE WORD, PAIRED WITH ITS PROSE. Both coverage gates ask a
+      # Every live WORD, paired with its prose. Both coverage gates ask a
       # question about this same walk and differ only in what they ask of
       # the prose, so they share it rather than each re-deriving the page
       # set — the two are meant to move together, and one drifting past
@@ -394,18 +394,18 @@ module Hecks
 
       def name_of(word, context) = "#{word} (#{context})"
 
-      # The coverage gate's question: every LIVE word with no prose yet.
+      # The coverage gate's question: every live word with no prose yet.
       def undocumented(directory)
         live_words(directory).reject { |_word, _context, prose| prose }
                              .map { |word, context, _| name_of(word, context) }
       end
 
-      # The SECOND coverage gate: prose is a declaration, and a
+      # The second coverage gate: prose is a declaration, and a
       # declaration nothing runs cannot disagree with anything. A word
       # documented only in sentences can go stale — or describe a word
       # the runtime never wired at all, which this repository has already
       # shipped twice (`read_model`'s where/order_by/limit/offset, and
-      # `role`/`goal` on a command). An example that RUNS is the only
+      # `role`/`goal` on a command). An example that runs is the only
       # documentation that can go red.
       def unexemplified(directory)
         live_words(directory).reject { |_word, _context, prose| exemplified?(prose) }

data/lib/hecks/embryonaut_bluebook.rb

@@ -1,12 +1,12 @@
 module Hecks
-  # A VENDORED, EXTERNAL BLUEBOOK — same shape as Framework (framework.rb),
+  # **A vendored, external bluebook** — same shape as Framework (framework.rb),
   # for members that don't ship inside hecks's own lib/ at all: a
   # separate, independently-versioned package
   # (github.com/chrisyoung/embryonaut_bluebooks) that a consuming project
-  # vendors into its OWN checkout, the same way a project already vendors
+  # vendors into its own checkout, the same way a project already vendors
   # hecks itself (bin/vendor_hecks, vendor/hecks/).
   #
-  # RECOVERED, NOT REBUILT — this module and its `uses_embryonaut_bluebook`
+  # **Recovered, not rebuilt** — this module and its `uses_embryonaut_bluebook`
   # DSL word (hecksagon_builder.rb) were built on a prior commit of this
   # repo (933d1dd), vendored out to a real consumer (lifeadelics/domain,
   # for embryonaut_bluebooks/payments), and then lost from this repo's own
@@ -17,19 +17,19 @@ module Hecks
   # conventions rather than copied wholesale, since the two trees had
   # otherwise diverged for weeks in both directions.
   #
-  # RESOLVED FROM THE CONSUMING REGISTRY'S OWN ROOT, not this gem's
+  # Resolved from the consuming registry's own root, not this gem's
   # __dir__ — Framework::ROOT can be a fixed, `__dir__`-relative constant
   # because framework members ship inside this gem; an embryonaut bluebook
-  # ships inside the CONSUMER's own checkout instead, at
+  # ships inside the consumer's own checkout instead, at
   # `<registry.root>/vendor/embryonaut_bluebooks/<name>/bluebook/`. There
   # is no fixed answer until a registry (and its root) actually exists, so
   # this resolves lazily, per call — the same reason `uses_framework`
   # itself only runs at hecksagon-build time, when a real registry is
   # current.
   #
-  # EVERY `.bluebook` FILE IN THE PACKAGE, SORTED — not just one. Unlike a
+  # Every `.bluebook` file in the package, sorted — not just one. Unlike a
   # framework member (one file, named by its own stem), a vendored package
-  # can span several bluebook files that reopen the SAME `Hecks.bluebook`
+  # can span several bluebook files that reopen the same `Hecks.bluebook`
   # (embryonaut_bluebooks/payments/bluebook/{payment,payments,policies}
   # .bluebook all reopen "Payments"). Load order matters — policies
   # .bluebook names `Payment::Succeed` and needs the aggregate already
@@ -37,16 +37,16 @@ module Hecks
   # payment < payments < policies, the same reason that package's own
   # files are named to fall in that order in the first place.
   #
-  # ONLY THE BLUEBOOK FILES — same restriction Framework draws, same
-  # reason: a `.hecksagon`/`.port`/`.adapter` is a WIRING decision
+  # **Only the bluebook files** — same restriction Framework draws, same
+  # reason: a `.hecksagon`/`.port`/`.adapter` is a wiring decision
   # (persistence, which processor adapter is bound) that belongs to
   # whoever is deploying, never baked into the vendored package itself.
   # embryonaut_bluebooks/payments ships its own mock `.hecksagon` for its
-  # own spec suite; a consumer declares its OWN separate
+  # own spec suite; a consumer declares its own separate
   # `Hecks.hecksagon "Payments" do ... end` to bind real storage/adapters
   # — see Framework's own comment for the fuller reasoning, identical here.
   #
-  # IDEMPOTENT THE SAME WAY Framework.load! IS — checked against the
+  # Idempotent the same way Framework.load! Is — checked against the
   # bluebook this package actually declares (`Naming.pascal("payments")`
   # => "Payments"), not a separate ledger. A vendored package's directory
   # name and its declared `Hecks.bluebook` name are the one convention

data/lib/hecks/facade/cli_door.rb

@@ -2,7 +2,7 @@ require_relative "../runtime/errors"
 
 module Hecks
   module Facade
-    # THE CLI DOOR — WHERE Facade MEETS A CALLER HOLDING FLAT STRINGS.
+    # **The CLI door** — where Facade meets a caller holding flat strings.
     #
     # `JsonDoor` beside this one translates for a caller holding parsed JSON:
     # String keys, already-nested objects, real Integers. A command line has
@@ -12,7 +12,7 @@ module Hecks
     # So this does the two things that turns into: rebuild the nesting, and
     # give every leaf the type the chapter declared for it.
     #
-    # THE TYPE COMES FROM THE PROJECTION, NEVER FROM THE VALUE. A door that
+    # The type comes from the projection, never from the value. A door that
     # guessed — "99 looks like a number" — would send the Integer 99 for a
     # version string of "99", and be wrong in a way nothing downstream could
     # detect, because both are perfectly good arguments. `Projector::CliProjector`
@@ -21,8 +21,24 @@ module Hecks
     module CliDoor
       module_function
 
+      # Builds a verb's nested, typed argument Hash out of the `name=value` words on a
+      # command line.
+      #
       # `["reference.value=BUG#1", "sequence.value=99"]` against a projected
       # verb spec -> `{ reference: { value: "BUG#1" }, sequence: { value: 99 } }`
+      #
+      # @param spec [Hash{Symbol => Object}] one verb's entry from `Projector::CliProjector`;
+      #   read for `:arguments` and the optional `:legacy_arguments`, each an Array of
+      #   option Hashes with `:path`, `:type` and, for a list, `:list`
+      # @param pairs [Array<String>] the words after the verb, each `path=value`; a path
+      #   may be the short form of a single-field value object (`reference` for
+      #   `reference.value`)
+      # @return [Hash{Symbol => Object}] the arguments nested by path, each leaf cast to
+      #   its declared type and each list option collected into an Array; `{}` for no pairs
+      # @raise [Runtime::NotFound] if a pair has no `=`, or names a path the verb does
+      #   not take
+      # @raise [Runtime::TypeMismatch] if a value cannot be read as the declared Integer
+      #   or Float
       def arguments(spec, pairs)
         # Legacy options are accepted but not printed in help. This lets an
         # existing id=... aggregate invocation cross the new receiver boundary
@@ -46,6 +62,12 @@ module Hecks
         end
       end
 
+      # Cuts one command-line word at its first `=`, so a value may itself contain `=`.
+      #
+      # @param pair [String] one word, such as `"reference.value=BUG#1"`
+      # @return [Array(String, String)] the path and the value; the value is `""` for
+      #   `"name="`
+      # @raise [Runtime::NotFound] if the word contains no `=`
       def split(pair)
         name, value = pair.split("=", 2)
         raise Runtime::NotFound, "#{pair.inspect} is not name=value" if value.nil?
@@ -53,16 +75,32 @@ module Hecks
         [name, value]
       end
 
-      # THE SHORT FORM, FOR THE COMMON CASE. Almost every value object in this
+      # Expands a bare value-object name into the full path of its only field.
+      #
+      # The short form, for the common case. Almost every value object in this
       # corpus has exactly one field, so `reference=BUG#1` is unambiguous and
       # is what anybody types. Expanded only when precisely one option starts
       # with that prefix — two would be a guess, and a guess about which field
       # a caller meant is worse than asking them to say.
+      #
+      # @param path [String] the path as typed, such as `"reference"`
+      # @param options [Hash{String => Hash}] the verb's options keyed by full path
+      # @return [String] the one full path beginning `"#{path}."`, or `path` unchanged when
+      #   none or several do
       def expand(path, options)
         candidates = options.keys.select { |key| key.start_with?("#{path}.") }
         candidates.length == 1 ? candidates.first : path
       end
 
+      # Converts one command-line value to the type the chapter declares for its field.
+      #
+      # @param value [String] the text after the `=`
+      # @param type [String] the declared type name; `"Integer"`, `"Float"` and
+      #   `"Boolean"` are converted, anything else leaves the value a String
+      # @return [Integer, Float, Boolean, String] the typed value; a Boolean is true only
+      #   for `true`, `yes` or `1` in any letter case, and false for every other text
+      # @raise [Runtime::TypeMismatch] if the text does not parse as the declared Integer
+      #   or Float
       def cast(value, type)
         case type
         when "Integer" then Integer(value)
@@ -74,27 +112,36 @@ module Hecks
         raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
       end
 
-      # A LIST GROWS RATHER THAN OVERWRITES, and getting this wrong is silent.
+      # Adds one element to a list argument, creating the list on first use.
+      #
+      # A list grows rather than overwrites, and getting this wrong is silent.
       #
-      # `tags.value=framework tags.value=model-checker` used to reach `bury`
-      # twice and store the second one alone — no refusal, no warning, one tag
+      # `tags.value=framework tags.value=model-checker` sent through `bury`
+      # twice would store the second one alone — no refusal, no warning, one tag
       # simply gone. That is the failure the interview named first: not the
       # loud kind, the kind where a value is forgotten and the caller has no
       # way to notice.
       #
-      # A LIST OF ONE IS STILL A LIST. `tags.value=flaky` produces
+      # A list of one is still a list. `tags.value=flaky` produces
       # `[{ value: "flaky" }]`, not `{ value: "flaky" }`, because the chapter
       # declared a collection and a caller who sent one element did not
-      # thereby declare a different shape. The old behaviour handed a bare
-      # object to a `list_of` attribute, and everything downstream that walks
+      # thereby declare a different shape. A bare object must never reach a
+      # `list_of` attribute: everything downstream that walks
       # it — a query's `contains`, a projection, the Postgres adapter's own
       # array handling — is entitled to assume it can iterate.
       #
-      # MULTI-FIELD ELEMENTS ARE NOT SUPPORTED HERE, deliberately. A flat
+      # Multi-field elements are not supported here, deliberately. A flat
       # command line has no way to say which `a.x=` goes with which `a.y=`,
       # and inventing an index syntax would be a language nobody asked for.
       # Every list in this corpus is a list of single-field value objects; a
       # richer one is a job for `JsonDoor`, which has real nesting.
+      #
+      # @param hash [Hash{Symbol => Object}] the arguments built so far; mutated in place
+      # @param path [Array<String>] the option's path segments, at least two: the last
+      #   names the element's field, the one before it names the list
+      # @param value [Integer, Float, Boolean, String] the cast value for the new element
+      # @return [Hash{Symbol => Object}] `hash`, with `{ leaf => value }` appended to the
+      #   Array at the list's key
       def append(hash, path, value)
         *branches, leaf = path.map(&:to_sym)
         holder = branches[0..-2].reduce(hash) { |node, key| node[key] ||= {} }
@@ -104,6 +151,13 @@ module Hecks
         hash
       end
 
+      # Sets one value at a nested path, creating each intermediate Hash on the way and
+      # overwriting whatever the leaf already held.
+      #
+      # @param hash [Hash{Symbol => Object}] the arguments built so far; mutated in place
+      # @param path [Array<String>] the option's path segments, outermost first
+      # @param value [Integer, Float, Boolean, String] the cast value to store at the leaf
+      # @return [Hash{Symbol => Object}] `hash`, with the value set under Symbol keys
       def bury(hash, path, value)
         *branches, leaf = path.map(&:to_sym)
         target = branches.reduce(hash) { |node, key| node[key] ||= {} }
@@ -111,6 +165,11 @@ module Hecks
         hash
       end
 
+      # Words the refusal for an argument the verb does not take, listing what it does.
+      #
+      # @param path [String] the path as the caller typed it
+      # @param known [Array<String>] every path the verb accepts, in any order
+      # @return [String] a one-line message naming `path` and the sorted accepted paths
       def unknown(path, known)
         "no argument #{path.inspect} — this verb takes #{known.sort.join(', ')}"
       end

data/lib/hecks/facade/cli_runner.rb

@@ -7,23 +7,44 @@ require_relative "../ports/clock"
 
 module Hecks
   module Facade
-    # THE RUNNER BEHIND A PROJECTED CLI.
+    # The runner behind a projected CLI.
     #
-    # `Projector::CliProjector` answers what a domain's command line LOOKS
+    # `Projector::CliProjector` answers what a domain's command line looks
     # like; this is the twenty lines that parse against it and dispatch. It
     # lives in `lib/` rather than in a `bin/` because more than one front door
     # wants it — `bin/run` for whichever domain you are standing in, `bin/qc`
     # pinned to the QA ledger — and a second copy of the parse-and-dispatch
     # would be the exact duplication the projection exists to avoid.
     #
-    # NO IO. It answers `[text, status]` and never prints or exits, so a spec
+    # No IO. It answers `[text, status]` and never prints or exits, so a spec
     # can call it without capturing streams or trapping SystemExit. The `bin/`
     # scripts do the printing, the same division `Router` and `JsonDoor`
     # already keep against HTTP.
     module CliRunner
       module_function
 
+      # Runs one command line against a booted domain: resolves the verb or question,
+      # parses its `name=value` arguments, dispatches or queries, and answers with the text
+      # to print.
+      #
       # `[text, status]` — status 0 answered, 1 refused or misused.
+      #
+      # Only the first bluebook in the registry (the booted domain's own) is projected
+      # into verbs. `--help`, `-h`, `help` or an empty `argv` answers the usage text; a
+      # verb followed by `--help` answers that verb's help.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain,
+      #   as `Hecks.boot` returns it
+      # @param argv [Array<String>] the words after the program name: an optional `ask`,
+      #   the verb or question name (bare or aggregate-qualified), then `path=value` pairs
+      # @param program [String] how the caller was invoked, echoed in usage and hints
+      # @return [Array(String, Integer)] the text to print and the exit status: 0 with
+      #   usage, help, or pretty-printed JSON of the outcome; 1 with a message when the
+      #   verb is unknown, an argument is wrong, a record is missing, or the domain refuses
+      # @raise [Runtime::WiringError] if a repository, or the clock adapter a `now`
+      #   argument needs, cannot be resolved
+      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every
+      #   retry
       def call(runtime:, argv:, program: "bin/run")
         bluebook = runtime.registry.bluebooks.values.first
         cli      = Projector.call(:cli, bluebook: bluebook, options: { program: program })
@@ -31,14 +52,14 @@ module Hecks
         name = argv.first
         return [cli[:usage], 0] if name.nil? || %w[--help -h help].include?(name)
 
-        # `ask` PUTS A QUESTION IN ITS OWN NAMESPACE — a chapter may declare a
+        # `ask` puts a question in its own namespace — a chapter may declare a
         # command and a query of one name, and banking does.
         asking = name == "ask"
         argv   = argv[1..] if asking
         name   = argv.first
         return [cli[:usage], 1] if name.nil?
 
-        # RESOLVED THROUGH THE ALIAS MAP, so `pizzas create_pizza` and
+        # Resolved through the alias map, so `pizzas create_pizza` and
         # `pizzas order.create_pizza` reach the same verb — the aggregate is
         # worth typing only when two of them declare the same word.
         pool = asking ? cli[:questions] : cli[:verbs]
@@ -56,6 +77,26 @@ module Hecks
         dispatch(runtime, spec, name, rest, program, asking)
       end
 
+      # Parses one resolved verb's arguments, runs it as a query or a command, and turns
+      # the outcome, or the domain's refusal, into printable text.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param spec [Hash{Symbol => Object}] the verb's entry from `Projector::CliProjector`;
+      #   read for `:kind`, `:verb`, `:arguments`, `:receiver` and `:legacy_receiver`
+      # @param name [String] the verb as the caller typed it, echoed in the `--help` hint
+      # @param rest [Array<String>] the `path=value` words after the verb
+      # @param program [String] how the caller was invoked, echoed in the `--help` hint
+      # @param asking [Boolean] whether the verb was reached through `ask`, which only
+      #   changes the wording of the hint
+      # @return [Array(String, Integer)] status 0 with pretty-printed JSON: the materialized
+      #   rows for a query; `id`, `state` and event names for a command; `id` and events
+      #   with payloads for a port operation. Status 1 with the message of a
+      #   `Runtime::DOMAIN_REFUSALS` error, followed by a `--help` hint when it is a
+      #   `Runtime::NotFound` or `Runtime::TypeMismatch`
+      # @raise [Runtime::WiringError] if a repository, or the clock adapter a `now`
+      #   argument needs, cannot be resolved
+      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every
+      #   retry
       def dispatch(runtime, spec, name, rest, program, asking)
         args = stamp_time(runtime, spec, CliDoor.arguments(spec, rest))
 
@@ -64,34 +105,36 @@ module Hecks
           return [JSON.pretty_generate(rows.map { |row| JsonDoor.materialize(row) }), 0]
         end
 
-        # THE ANSWER IS SCOPED TO WHAT WAS ASKED. `bin/run`'s step-list form
+        # The answer is scoped to what was asked. `bin/run`'s step-list form
         # reports the whole store because a corpus run is judged on all of it;
         # somebody who issued one verb wants that verb's outcome, and against a
         # Postgres-backed domain the full dump is every record there has been.
         request = CommandRequest.normalize(args, receiver:        spec[:receiver],
                                                  legacy_receiver: spec[:legacy_receiver])
-        handle = runtime.dispatch(spec[:verb], **request)
+        handle = runtime.dispatch_flat(spec[:verb], request)
         return [JSON.pretty_generate(answered(handle)), 0] if handle.state.nil?
 
         [JSON.pretty_generate(id:     handle.id,
                               state:  JsonDoor.materialize(handle.state),
                               events: handle.events.map(&:name)), 0]
       rescue Runtime::NotFound, Runtime::TypeMismatch => e
-        # A BAD ARGUMENT AND A MISSING RECORD BOTH LAND HERE, and both want the
+        # A bad argument and a missing record both land here, and both want the
         # same next step: read what the verb actually takes.
         ["#{e.message}\n\n  #{program} #{'ask ' if asking}#{name} --help", 1]
       rescue *Runtime::DOMAIN_REFUSALS => e
-        # THE REFUSAL IS THE PRODUCT — the chapter's own sentence, verbatim.
+        # **The refusal is the product** — the chapter's own sentence, verbatim.
         [e.message, 1]
       end
 
-      # THE CLOCK, FILLED IN AT THE DOOR.
+      # Supplies the current time for a verb that takes a `now` argument the caller left out.
+      #
+      # The clock, filled in at the door.
       #
       # A staleness rule needs the time, and the sublanguage cannot ask for it
       # — a `given` that read the clock would judge the same record differently
       # on two runs, and every replay, audit and fuzz oracle here assumes it
-      # does not. So `now` stays an ARGUMENT the predicate merely reads, and
-      # the question becomes who types it. Before this, the caller did:
+      # does not. So `now` stays an argument the predicate merely reads, and
+      # the question becomes who types it. Left to the caller, that is:
       #
       #   qa/quality_control target.claim id=QC held_by.value=me \
       #     now.value=$(date +%s) window.value=900
@@ -99,20 +142,20 @@ module Hecks
       # which is a shell incantation in front of every claim, and one an agent
       # gets wrong by pasting a stale number.
       #
-      # AT THE DOOR, NOT IN THE RUNTIME, and the distinction is load-bearing.
+      # At the door, not in the runtime, and the distinction is load-bearing.
       # `Ports::IdentityGeneration` reasons the same question through for a
       # minted uuid and lands on "the value is baked into the caller's args at
-      # the first live dispatch". A clock consulted INSIDE the interpreter
+      # the first live dispatch". A clock consulted inside the interpreter
       # would not have that property — a recorded corpus step replayed
       # tomorrow would quietly get tomorrow's time, and the fuzzer's oracle and
       # the adapter-agreement gate both compare runs of exactly that shape. Here
       # it fills only what a person or an agent is typing, and `runtime.dispatch`
       # is left alone.
       #
-      # AN EXPLICIT VALUE ALWAYS WINS, so a spec or a caller reproducing a
+      # An explicit value always wins, so a spec or a caller reproducing a
       # moment says so and is believed. This only supplies what was omitted.
       #
-      # BY NAME, WHICH IS THE ONE UNCOMFORTABLE PART. `now` is a plausible
+      # By name, which is the one uncomfortable part. `now` is a plausible
       # domain word and nothing declares that it means the clock. It is
       # tolerable because this is a convenience layer rather than semantics —
       # the verb's own help says the argument exists, dispatch is unchanged,
@@ -120,6 +163,17 @@ module Hecks
       # declaration in the chapter (`attribute :now, Instant, from: :clock`),
       # which is a language change: DSL, IR, the self-hosted grammar and its
       # goldens. Worth doing; not worth smuggling in here.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain,
+      #   whose registry names the clock adapter
+      # @param spec [Hash{Symbol => Object}] the verb's projected entry; only an option whose
+      #   `:path` starts `"now."` makes this method act
+      # @param args [Hash{Symbol => Object}] the parsed arguments; not mutated
+      # @return [Hash{Symbol => Object}] `args` itself when the verb takes no `now` or the
+      #   caller gave one; otherwise a copy with `now: { value: seconds }`, the clock port's
+      #   current time in whole seconds
+      # @raise [Runtime::WiringError] if the time is needed and zero or several adapters
+      #   implement the clock port
       def stamp_time(runtime, spec, args)
         return args unless spec[:arguments].any? { |argument| argument[:path].start_with?("now.") }
         return args if args.key?(:now)
@@ -127,12 +181,15 @@ module Hecks
         args.merge(now: { value: Ports::Clock.now(runtime.registry) })
       end
 
-      # A PORT OPERATION HAS NO STATE, AND ITS PAYLOAD IS THE ENTIRE POINT.
+      # Shapes a port operation's outcome for printing: the record asked about, and each
+      # event with its full payload.
+      #
+      # A port operation has no state, and its payload is the entire point.
       #
       # A command answers with the record it changed, so naming the events is
       # enough — the interesting part is in `state`. A port operation changes
       # no record: it asked something outside and came back with what was
-      # said, and that lives ONLY in the event payload. Reporting names alone
+      # said, and that lives only in the event payload. Reporting names alone
       # would print `SpecsCompleted` and drop the spec output on the floor.
       #
       # This is what makes a projected CLI usable as somebody's only door. An
@@ -140,13 +197,19 @@ module Hecks
       # it asks the port and reads the answer, and if the answer is a bare
       # event name then the door leads nowhere and it needs a shell after all.
       #
-      # BOTH ENDINGS COME BACK THE SAME WAY, and the status stays 0 for both.
+      # Both endings come back the same way, and the status stays 0 for both.
       # A refusal here is not a misuse — `IssueStillOpen` and `SuiteFailed`
       # are answers the caller asked for, correctly delivered. Exit 1 is for
       # "you typed something wrong", and conflating the two would have a
       # scripted agent treat a healthy no as a broken call.
+      #
+      # @param handle [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
+      #   dispatch result, which for a port operation has a nil `state`
+      # @return [Hash{Symbol => Object}] `:id`, the result's id or else the first event's
+      #   (nil when there is neither), and `:events`, an Array of `{ name:, payload: }`
+      #   Hashes with each payload materialized to plain data
       def answered(handle)
-        # THE ID COMES OFF THE EVENT, because a port operation hydrates no
+        # The ID comes off the event, because a port operation hydrates no
         # instance and the handle's own `id` is nil by design. The event knows
         # which record was asked about — it was stamped with it — and printing
         # `null` beside a payload that plainly says `SW-TOOL` would read as a
@@ -157,15 +220,27 @@ module Hecks
           end }
       end
 
-      # A NEAR MISS IS WORTH MORE THAN A LIST. Somebody who typed
+      # Words the answer to a verb or question that does not exist, suggesting up to five
+      # names that start the same way.
+      #
+      # A near miss is worth more than a list. Somebody who typed
       # `bug.discovr` wants one line, not eighty-seven of them.
       #
-      # RANKED BY SHARED PREFIX, not by substring. Substring was the first
-      # attempt and it finds nothing for the commonest typo of all — a dropped
+      # Ranked by shared prefix, not by substring. Substring matching finds
+      # nothing for the commonest typo of all — a dropped
       # letter, `order.create_piza`, which is a substring of nothing. Prefix
       # length survives an error anywhere after it, which is where errors are.
+      #
+      # @param cli [Hash{Symbol => Object}] the `Projector::CliProjector` projection; read
+      #   for `cli[:names]`, the alias maps under `:command` and `:question`
+      # @param name [String] what the caller typed
+      # @param asking [Boolean] whether it was typed after `ask`, which picks the question
+      #   names and the wording
+      # @param program [String] how the caller was invoked, echoed in the closing hint
+      # @return [String] a multi-line message; candidates must share a prefix of at least
+      #   half of `name`'s length, and never fewer than three characters
       def unknown(cli, name, asking, program)
-        # BOTH SPELLINGS ARE CANDIDATES. A caller who typed the qualified
+        # **Both spellings are candidates**. A caller who typed the qualified
         # form with a typo — `order.create_piza` — shares no prefix with the
         # short name `create_pizza`, so pooling only one of them suggests
         # nothing for half the mistakes anybody makes.
@@ -181,6 +256,12 @@ module Hecks
         lines.join("\n")
       end
 
+      # Counts how many leading characters two names have in common.
+      #
+      # @param one [String] a candidate name
+      # @param other [String] the name to compare it with
+      # @return [Integer] the length of the common prefix, from 0 up to the shorter
+      #   name's length
       def shared_prefix(one, other)
         length = [one.length, other.length].min
         (0...length).find { |index| one[index] != other[index] } || length