hecks 2.7.0 → 2.9.0

data/lib/hecks/bluebook/dsl/identity_declaration.rb

@@ -1,68 +1,19 @@
 module Hecks
   module Bluebook
     module DSL
-      # `identified_by` — shared by AggregateBuilder and EntityBuilder
-      # only (S9, ADR 0025 — "EntityBuilder's duplicate identified_by and
-      # resolve_pending_identity! go"): a piece's own identity cannot
-      # spell differently from its aggregate's, and until this slice it
-      # was hand-duplicated onto both rather than shared.
-      #
-      # A separate module from AttributeCollector on purpose — every
-      # `attribute()`-taking builder (Command, Query, PortOperation,
-      # ValueObject, ...) `include`s that one too, and none of them
-      # declares an identity of its own ; folding `identified_by` in
-      # there made it answer for six builders that never earned the
-      # word (`syntax_conformance_spec.rb` catches exactly this — a
-      # builder answering a method the grammar never grants it).
-      #
-      # Requires its includer to also `include AttributeCollector`
-      # (for `attributes`/`resolve_identity_field!`/`resolve_identity_
-      # type!`, still declared there since every includer of that
-      # module needs them) and to supply `identity_pool` (private) —
-      # the value-object list a bare field's own type resolves
-      # against: AggregateBuilder's own `@value_objects + closed_sets`,
-      # or EntityBuilder's owner's, since a piece mints none of its own.
+      # `identified_by`, shared by AggregateBuilder and EntityBuilder (ADR 0025).
+      # The includer must include AttributeCollector and define a private `identity_pool`.
       module IdentityDeclaration
-        # Records which of the three live `identified_by` forms a builder declared, deferring
-        # resolution until build time.
-        #
-        # There are three live forms, deliberately distinguishable at the
-        # declaration site:
+        # Records which `identified_by` form a builder declared; resolution waits for build time.
         #
         #   identified_by AccountNumber, as: :number # one identity concept
         #   identified_by do ... end                 # a bespoke concept
         #   identified_by :branch, :number           # an existing compound key
         #
-        # One symbol is retired: it cannot say whether the author means a
-        # value concept or a field-shaped database key. Frozen source still
-        # reaches the old interpretation through `legacy_identified_by`.
-        # Both `AggregateBuilder` and `EntityBuilder` name this method in their Keyword rows'
-        # `calls:` column, so `GenericDispatch` forwards `identified_by` here unchanged, both
-        # after boot (reading the live grammar table) and during it
-        # (`GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, which carries every `calls:`-routed row
-        # unconditionally, not a hand-picked bootstrap-reachable subset — though this one is
-        # exercised during boot too, since every self-hosted aggregate/entity declares an identity).
-        # Dispatches across the three live forms documented above (value-
-        # object + block, single type target, single/compound field
-        # target), each an early return that sets exactly one pending
-        # ivar. Splitting per form would need each branch's own `return`-
-        # with-nil semantics and the shared `@name`/`identity_pool`
-        # threaded back out as parameters, for no gain beyond what the
-        # three-forms comment above already documents.
-        #
-        # @param targets [Array<Symbol, Module>] zero or more identity targets: a value-object
-        #   type (a bareword, resolved by `ConstShim` to a `Module`), one or more attribute-name
-        #   symbols for a field or compound key, or empty when `definition` is given
-        # @param as [Symbol, nil] the field name to mint for a value-object-type target; not
-        #   accepted with a field or compound-key target
-        # @yield a bespoke value-object body, `instance_eval`'d by `ValueObjectBuilder.build` to
-        #   mint the identity's own anonymous value object
-        # @return [Array<Symbol>, Array<String>, nil] `targets` when a compound key is declared,
-        #   the resolved identity paths from `legacy_identified_by` in shadow-parsing mode, or
-        #   `nil` otherwise; callers reach this through `GenericDispatch`, which discards it
-        # @raise [Bluebook::DSL::Malformed] if `identified_by` was already called, combines a
-        #   block with targets, names no identity, mixes a value-object type with field names,
-        #   passes `as:` with a field or compound key, or the block declares no attributes
+        # @param targets [Array<Symbol, Module>] a value-object type or attribute names
+        # @param as [Symbol, nil] the field name to mint for a value-object-type target
+        # @yield a bespoke value-object body for the identity's own value object
+        # @raise [Bluebook::DSL::Malformed] on a repeat declaration or an invalid mix of forms
         # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
         def identified_by_impl(*targets, as: nil, &definition)
           return legacy_identified_by(*targets, as: as, &definition) if MetaValidator.shadow_parsing?
@@ -84,20 +35,8 @@ module Hecks
                   &definition
                 )
               rescue NameError => e
-                # A removed spelling must refuse loudly, not degrade into a raw
-                # Ruby error — the one contract `EraGuard.shadow_parse` leans
-                # on to know a normal parse genuinely could not read this text
-                # (only `Malformed` triggers its shadow-mode retry, era_guard.rb's
-                # own comment). The old `identified_by { name.value }` — a block
-                # whose text was never called, only extracted (legacy_
-                # identified_by, below) — is exactly this shape: read under the
-                # current grammar it is instead instance_eval'd as a value-object
-                # definition, and a bare identifier like `name` inside it resolves
-                # to nothing WordGate#method_missing recognizes, so Ruby itself
-                # raises NameError. Left uncaught, that NameError skipped
-                # shadow_parse's rescue entirely and reached callers as a raw
-                # crash instead of the frozen-era fallback that exists for
-                # precisely this text.
+                # Must raise Malformed: EraGuard.shadow_parse retries frozen text only on
+                # Malformed, and a bare identifier in an old block form raises NameError here.
                 raise Malformed,
                       "#{@name}.identified_by do ... end could not be read as a value-object " \
                       "definition: #{e.message}"
@@ -122,10 +61,7 @@ module Hecks
               raise Malformed,
                     "#{@name}.identified_by takes no as: — name the declared field itself"
             end
-            # Transitional compatibility: the self-hosted language and live
-            # corpus still contain this form. Keep it readable until their
-            # exemplar-led migration is complete; the final lifecycle cutover
-            # replaces this assignment with the targeted refusal.
+            # Transitional: the self-hosted language and live corpus still use this form.
             @identity_field_pending = field
             return
           end
@@ -141,11 +77,7 @@ module Hecks
 
         private
 
-        # Resolves whichever of the three `identified_by` shapes is
-        # pending, against `identity_pool` — the includer's own private
-        # hook. Called at build time, not at `identified_by`'s own call
-        # time — see `AttributeCollector#resolve_identity_field!`'s own
-        # comment on why.
+        # Resolves the pending identity against `identity_pool` at build time, not call time.
         def resolve_pending_identity!
           if @identity_type_pending
             type, as, insert_at = @identity_type_pending
@@ -162,11 +94,7 @@ module Hecks
         def identity_type?(target) = target.to_s.match?(/\A[A-Z]/)
 
         def refuse_second_identity!
-          # During the staged migration a transitional one-symbol declaration
-          # may be replaced by the new declaration later in the same builder.
-          # This keeps existing builder fixtures/source readable while their
-          # exemplar is migrated. Once one-symbol identity is retired this
-          # compatibility branch disappears with it.
+          # Transitional: a one-symbol declaration may still be replaced by a later one.
           if @identity_field_pending && !@identity_type_pending && !@identity_fields_pending
             @identity_field_pending = nil
             return
@@ -178,10 +106,7 @@ module Hecks
           raise Malformed, "#{@name} declares identified_by more than once"
         end
 
-        # Legacy — the two removed spellings (a value object + as:, and the
-        # multi-line block), kept alive only for `EraGuard.shadow_parse`
-        # (S0a, ADR 0025) to still make sense of frozen era text that used
-        # them; unreachable outside `MetaValidator.shadow_parsing?`.
+        # Parses the spellings frozen era text uses, for `EraGuard.shadow_parse`.
         def legacy_identified_by(*targets, as:, &path)
           target = targets.first
           if target

data/lib/hecks/bluebook/dsl/lifecycle_builder.rb

@@ -2,11 +2,7 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses a `lifecycle :field, default: ... do transition ... end`
-      # block into a `Lifecycle` — the field an aggregate or entity's own
-      # state machine lives on, its starting value, and the `command =>
-      # target_state` transition table (with an optional `from:` guard)
-      # each `transition_impl` call adds a row to.
+      # Parses a `lifecycle :field, default: ... do transition ... end` block into a `Lifecycle`.
       class LifecycleBuilder
         GRAMMAR_CONTEXT = "Lifecycle".freeze
 
@@ -22,11 +18,7 @@ module Hecks
 
         # Records one transition row per command in `mapping`, all sharing its `from:` guard.
         #
-        # Answers the `transition` word, which the grammar table routes here
-        # through its `calls:` column — item #13's full metaprogrammed
-        # dispatch (slice 4c). Bootstrap-reachable (syntax.bluebook's
-        # own Keyword/Argument entities describe their `status`
-        # lifecycle with it), so in `BOOTSTRAP_CALLS_FALLBACK`.
+        # Listed in `BOOTSTRAP_CALLS_FALLBACK` because syntax.bluebook uses it during boot.
         #
         # @param mapping [Hash{String, Symbol => String, Symbol, Array<String>}] command name to
         #   target state, as in `"Purchase" => "sold"`; the optional `:from` key holds the
@@ -70,17 +62,11 @@ module Hecks
 
         private
 
-        # C5.3 (docs/semantics/bluebook-semantics.md) — two transitions for
-        # one command whose `from:` sets overlap (or where either has no
-        # `from:` at all) were silently first-wins; refused where the state
-        # machine can be read whole. Two transitions for one command from
-        # disjoint states are the legitimate shape (`match_transition`
-        # picks by the current state) and stay. A `from:` naming a state
-        # nothing declares is not refused here: it is a reachability
-        # finding `bin/model_check` already reports (unreachable state,
-        # dead transition), and a bluebook may declare it on purpose.
+        # C5.3 (docs/semantics/bluebook-semantics.md): overlapping `from:` sets for one command
+        # are refused. Disjoint sets are legitimate. An undeclared `from:` state is left to
+        # `bin/model_check`.
         def refuse_ambiguity!
-          return if MetaValidator.shadow_parsing? # frozen era text is history
+          return if MetaValidator.shadow_parsing? # frozen era text is exempt
 
           @transitions.each_with_index do |(command, transition), index|
             earlier = @transitions[0...index].find do |other_command, other|

data/lib/hecks/bluebook/dsl/policy_builder.rb

@@ -2,12 +2,8 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses a `policy "Name" do ... end` block into a `Policy` — a
-      # reaction wired at chapter scope: `on` the event it watches, an
-      # optional `where` guard evaluated against the event's own payload, an
-      # optional `for_each` fan-out query, and the `trigger` command it
-      # dispatches (`with:` projecting the event's payload onto the
-      # command's own arguments when the two shapes differ).
+      # Parses a `policy "Name" do ... end` block into a `Policy`: the event it reacts to (`on`),
+      # an optional `where` guard, an optional `for_each` fan-out, and the `trigger` it dispatches.
       class PolicyBuilder
         GRAMMAR_CONTEXT = "Policy".freeze
 
@@ -20,20 +16,8 @@ module Hecks
 
         # Records the event this policy reacts to.
         #
-        # `on Account::AccountFrozen` — a bare constant accepted (ADR
-        # 0025, S6 — "events first-class"), resolved through `ConstShim`
-        # the same way `trigger`/`dispatch` already resolve a command
-        # reference (`Naming.event_ref`, that method's own header). Not
-        # a required spelling yet, unlike `trigger`'s own quoted-text
-        # refusal — see `policy.bluebook`'s own KeywordSeed comment for
-        # why: event names aren't 100% migrated across the live corpus
-        # the way command references are, so both `on "Account.
-        # AccountFrozen"` (quoted) and `on Account::AccountFrozen`
-        # (bare) stay admitted until a full migration lands.
-        #
-        # Reached through `calls: "on_impl"` rather than `GenericDispatch`'s generic single-fill
-        # coercion, the same way `trigger_impl` below overrides its own generic default — `on`
-        # admits both a bare constant and quoted text, not one single argument kind.
+        # Reached through `calls: "on_impl"` because `on` admits both a bare constant
+        # (`on Account::AccountFrozen`) and quoted text, not one single argument kind.
         #
         # @param event_ref [Symbol, String, Module] the event, as a bare constant (a
         #   `ScopedConstant` module `ConstShim` resolves) or quoted text
@@ -42,45 +26,16 @@ module Hecks
           @on_event = Naming.event_ref(event_ref)
         end
 
-        # Records the command this policy dispatches and, optionally, how the event's payload
-        # projects onto it.
-        #
-        # `with:` — what the trigger is given, when the event's own shape
-        # is not it. Omitted, the whole event payload forwards verbatim.
-        #
-        # Same `key => value` shape a saga's own `dispatch ..., with:`
-        # takes, and read the same way at runtime: a Symbol names a field
-        # on the triggering event, anything else is a literal the policy
-        # supplies itself. The reason it exists is the reason a saga's
-        # does — a reaction crosses an aggregate boundary, and the event
-        # on one side is under no obligation to be shaped like the
-        # command on the other. Without it the target has to declare
-        # every field the event happens to carry, whether it reads them
-        # or not.
-        # The command itself, not its name (ADR 0025, "events and
-        # reactions" — command references become first-class): `trigger
-        # Account::Debit`, a bare constant `ConstShim` resolves the same
-        # way `reference_to Account` always has, not a quoted verb string.
-        # Matches the qualified-or-not shape a saga's own `dispatch`
-        # command name takes — see `Naming.command_ref`'s own header for
-        # how the `::`/`.` rewrite works, and `SagaInterpreter#qualified`
-        # for why an unqualified form is always enough (same-domain is
-        # the fallback, so `Account::Debit` and `Banking::Account::Debit`
-        # mean the same thing here).
+        # Records the command this policy dispatches and how the event payload projects onto it.
         #
-        # Legacy under shadow-parsing (S0a's own bridge) — frozen era
-        # text still writes the quoted form.
+        # With `with:`, a Symbol value names a field on the triggering event and anything else is
+        # a literal. Omitted, the whole payload forwards.
+        # In `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
         #
-        # `["Policy", "trigger"] => :trigger_impl` is in
-        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, which carries every `calls:`-routed row
-        # unconditionally — this one is also exercised during boot itself, since every
-        # self-hosted policy declares a trigger.
-        #
-        # @param command_ref [Symbol, String, Module] the command, as a bare constant (a
-        #   `ScopedConstant` module `ConstShim` resolves) or, under shadow-parsing, quoted text
-        # @param with [Hash{Symbol => Object}, nil] a projection from the triggering event's payload
-        #   onto the command's own arguments; a Symbol value names an event field, anything else is
-        #   a literal; `nil` forwards the whole event payload verbatim
+        # @param command_ref [Symbol, String, Module] the command, as a bare constant or, under
+        #   shadow-parsing, quoted text
+        # @param with [Hash{Symbol => Object}, nil] event payload to command arguments;
+        #   `nil` forwards the whole payload
         # @return [void]
         # @raise [Bluebook::DSL::Malformed] if `command_ref` is quoted text outside shadow-parsing
         def trigger_impl(command_ref, with: nil)
@@ -97,13 +52,8 @@ module Hecks
 
         # Records the domain this policy's trigger reaches into.
         #
-        # `across "Notifications"` names the domain a trigger reaches into.
-        # `expect_undelivered: true` declares that this domain expects that
-        # target never to be reached (no such domain, on purpose), which
-        # `ModelCheck` holds it to in both directions. Reached through
-        # `calls: "across_impl"` rather than the generic single-fill
-        # coercion, because `expect_undelivered:` is a keyword argument the
-        # generic coercion cannot take.
+        # `expect_undelivered: true` declares that the target is expected never to be reached
+        # (no such domain, on purpose); `ModelCheck` holds it to that in both directions.
         #
         # @param domain [String, Symbol] the target domain's name
         # @param expect_undelivered [Boolean] whether this domain expects `across`'s target to
@@ -117,20 +67,8 @@ module Hecks
         # Records the guard predicate that decides whether this policy applies to a triggering
         # event.
         #
-        # **The guard** — same extraction CommandBuilder#given/#ensures already
-        # use (Ports::Extraction reads the block's source ; the block itself
-        # is never called, here or at runtime — Runtime::PolicyInterpreter
-        # evaluates the extracted text through the same
-        # Bluebook::Expression::Evaluator a command's own given/ensures run
-        # through). No description argument the way given/ensures each
-        # carry one : a given's description becomes a GivenNotMet message,
-        # and a where that does not hold refuses nothing — it just means
-        # this policy does not apply to this event, exactly like an
-        # `event_qualifier` miss, which carries no message either.
-        #
-        # Evaluated against the triggering event's own payload, not a
-        # stored record — a policy reacts to what just happened, and has no
-        # aggregate instance of its own to read state from.
+        # The block's source is extracted and never called; a `where` that does not hold refuses
+        # nothing, so unlike `given` it takes no description. It sees the event's payload only.
         #
         # @yield the guard predicate, extracted as source text and evaluated later by
         #   `Runtime::PolicyInterpreter` against the triggering event's payload; never called here
@@ -147,22 +85,12 @@ module Hecks
                   "could not be read, so no other runtime could ever evaluate it"
           end
 
-          # C3.6 — the same PatternSubset check every rule site gets.
           ast = Expression::AstJson.emit_predicate(canonical)
           Expression::AstJson.refuse_unshared_patterns!(ast, owner: @name, word: "where")
           Expression::AstJson.refuse_unresolvable_lookups!(ast, owner: @name, word: "where")
           @where = canonical
         end
 
-        # **The fan-out source** — a query verb, "Aggregate.query_name" or
-        # "Domain::Aggregate.query_name", the same qualified-or-not shape a
-        # saga's own `dispatch` command name already takes
-        # (SagaInterpreter#qualified). Runtime::PolicyInterpreter runs the
-        # named query against the triggering event's own payload and fires
-        # `trigger` once per row, instead of once for the event.
-        # `for_each` — item #13's full metaprogrammed dispatch, slice 1:
-        # same shape as `on`, above.
-
         # Builds the `Policy` this builder has accumulated.
         #
         # @return [Bluebook::Policy] the built policy, carrying every field set by `on`,

data/lib/hecks/bluebook/dsl/port_builder.rb

@@ -38,12 +38,8 @@ module Hecks
 
         # Declares one method an adapter bound to this port must respond to.
         #
-        # **The method contract** — the fact a `.port` file's `verb`/`signal`
-        # never carried: what an adapter must actually respond to for a
-        # dispatch to reach it without a bare `NoMethodError`. Declared the
-        # same repeatable way `AdapterBuilder#field`/`#secret` already are,
-        # so `verify!` can check it with `respond_to?` at boot instead of
-        # the runtime discovering it live.
+        # Repeatable, like `AdapterBuilder#field`; `verify!` checks each name with `respond_to?`
+        # at boot so a dispatch never meets a bare `NoMethodError`.
         #
         # @param name [Symbol, String] the method name, such as `:ask`
         # @return [Array<Symbol>] every method declared so far, this one last

data/lib/hecks/bluebook/dsl/port_operation_builder.rb

@@ -2,40 +2,17 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses one `operation`/`tells`/`asks` block inside a `domain_port`
-      # into a `PortOperation` — its own attributes (the external fact's
-      # payload) plus either the events it `emits` (inbound) or the
-      # `answers`/`refuses` pair naming its two possible outcomes (outbound).
-      # `to:` records which aggregate the operation routes to as dispatch
-      # metadata, never as an attribute — see `to:`'s own comment below.
+      # Parses one `operation`/`tells`/`asks` block into a `PortOperation`: its attributes plus
+      # either the events it `emits` (inbound) or its `answers`/`refuses` pair (outbound).
       class PortOperationBuilder
         GRAMMAR_CONTEXT = "PortOperation".freeze
 
         include AttributeCollector
         include WordGate
 
-        # `to:` — the sanctioned replacement for `reference_to` inside an
-        # operation body: `reference_to_impl`'s own refusal message tells
-        # authors to "pass the receiving aggregate in to:", and this is
-        # the argument DomainPort's own grammar (domain_port.bluebook)
-        # gives operation/tells/asks to receive it.
-        #
-        # **Genuine routing metadata, not an attribute** — matching
-        # rust/parser/src/parse/domain_port.rs's own header comment ("The
-        # receiving aggregate is routing metadata supplied by to:, not an
-        # operation attribute"), which anticipated this shape before either
-        # side actually built it. Stored separately (below, threaded to
-        # PortOperation as `to:`) rather than reusing reference_to_impl's
-        # own attribute-adding path — Dispatcher#port_invocation
-        # (lib/hecks/runtime/dispatcher.rb) is the one place that resolves
-        # routing at dispatch time; it gained a second, purely additive
-        # branch for this (falls back to a plain attribute named for the
-        # owning aggregate's own identified_by field, the same "declare
-        # only external facts with attribute" the refusal message
-        # describes) rather than folding `to:` into identity_attribute's
-        # existing Reference-attribute scan, which every operation already
-        # in the corpus (Banking, pizzas, a client site's own vendored
-        # PaymentGateway) still relies on unchanged.
+        # `to:` is the sanctioned replacement for `reference_to` inside an operation body —
+        # genuine routing metadata, not an attribute, resolved at dispatch time by
+        # `Dispatcher#port_invocation` rather than folded into the ordinary attribute scan.
         #
         # @param name [String] the operation's name
         # @param to [Symbol, String, Module, nil] the aggregate the operation routes to; stored
@@ -50,33 +27,13 @@ module Hecks
           @emits     = []
         end
 
-        # Refuses `reference_to` inside an operation body, except while shadow-parsing, where it
-        # adds the reference attribute frozen era text declared.
-        #
-        # Always an attribute, never the self-reference `CommandBuilder`
-        # spells — a port operation has no `creates?`/`acts_on` distinction
-        # to protect, so there is nothing for the self-reference branch to be
-        # for here. `reference_to Payment, as: :payment_id` reads the same
-        # even though the target happens to equal the owning aggregate.
-        # Answers the `reference_to` word through the table's `calls:`
-        # column — item #13's full metaprogrammed dispatch (slice 4b).
-        # Bootstrap-reachable, in `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
-        #
-        # Disabled, #335 — kept only for MetaValidator's own shadow-parsing
-        # pass (the self-hosted grammar's own KeywordSeed/ArgumentSeed rows
-        # for "reference_to" in this context are themselves declared using
-        # this construct, one level up — deleting the Ruby method would
-        # break the language describing itself, not just old domain
-        # authors). Every real domain author reaches `to:` instead, above —
-        # a genuinely different mechanism now, not a relocated spelling of
-        # this one (see `to:`'s own comment).
+        # Refuses `reference_to` inside an operation body; a port operation has no self-reference
+        # to protect the way `CommandBuilder`'s does. Kept only for MetaValidator's own
+        # shadow-parsing pass, which still declares itself using this construct — every real
+        # domain author reaches `to:` instead (see its own comment above).
         #
-        # @param type [Symbol, String, Module] the referenced aggregate, written as a bare constant
-        # @param as [Symbol, nil] the attribute's name; nil derives it from the target, as in
-        #   `:payment_id` under shadow-parsing
-        # @return [nil] nothing useful; the reference lands in `attributes`
-        # @raise [Bluebook::DSL::Malformed] always outside shadow-parsing, since routing belongs
-        #   in `to:`; under shadow-parsing, if the attribute name is already declared
+        # @raise [Bluebook::DSL::Malformed] always outside shadow-parsing; under shadow-parsing,
+        #   if the attribute name is already declared
         def reference_to_impl(type, as: nil)
           unless MetaValidator.shadow_parsing?
             raise Malformed,
@@ -88,25 +45,14 @@ module Hecks
         end
 
         # Names one event an inbound operation records once the external fact has arrived.
-        #
-        # @param event_name [String, Symbol] the event's name, such as `"PaymentSettled"`
-        # @return [Array<String>] every event named so far, this one last
         def emits(event_name) = @emits << event_name.to_s
 
-        # The two halves of an `asks`. An outbound call has exactly two
-        # endings and the chapter names both — `answers` for what came back,
-        # `refuses` for what the outside said instead. They are separate words
-        # rather than two `emits` because a reader has to be able to tell them
-        # apart without reading the adapter: one is the thing you wanted, the
-        # other is the thing you have to handle.
-        # `answers`/`refuses` — item #13's full metaprogrammed dispatch,
-        # slice 1 (whole-project table-unification survey): both a bare,
-        # kind-driven coerce-and-assign with nothing else, now executed
-        # by `GenericDispatch`.
+        # `answers`/`refuses`, the two halves of an `asks` — separate words rather than two
+        # `emits` so a reader can tell what came back from what the outside refused, without
+        # reading the adapter.
 
         # Assembles the operation, refusing words that belong to the other direction.
         #
-        # @return [Bluebook::PortOperation] the operation with its attributes, events and routing
         # @raise [Bluebook::DSL::Malformed] if an inbound operation declares no `emits` or
         #   declares `answers`/`refuses`, or an outbound one declares `emits` or lacks either
         #   `answers` or `refuses`
@@ -119,9 +65,8 @@ module Hecks
             direction: @direction, answers: @answers, refuses: @refuses, to: @to
           )
 
-          # An inbound operation still has to say something. Only inbound: an
-          # `asks` says it with `answers`/`refuses` instead, and
-          # `refuse_wrong_words!` above has already insisted on both.
+          # Only inbound: an `asks` says it with `answers`/`refuses` instead, already enforced
+          # above.
           if !outbound && @emits.empty?
             raise Malformed,
                   "#{@name} declares no emits — an operation with nothing to say " \
@@ -133,21 +78,15 @@ module Hecks
 
         private
 
-        # The one place a reference attribute actually gets added — both
-        # `to:` (initialize, above) and reference_to_impl's own shadow-
-        # parsing branch call this, so there is exactly one real
-        # implementation of "carry a Reference-typed external fact,"
-        # not two that could drift.
+        # The one real implementation of "carry a Reference-typed external fact" — both `to:` and
+        # `reference_to_impl`'s shadow-parsing branch call this, so there is nothing to drift.
         def add_reference!(type, as: nil)
           target = Naming.demodulise(type)
           attribute_impl(as || default_reference_name(target), Reference.new(target))
         end
 
-        # **Each direction refuses the other's words**. `emits` on an `asks` looks
-        # right and is not: it would name one ending and leave the other
-        # nowhere. `answers` on a `tells` is worse — there is no channel back
-        # to an inbound caller at all, so it would read as a promise the
-        # runtime cannot keep.
+        # Each direction refuses the other's words: `emits` on an `asks` names one ending and
+        # leaves the other nowhere; `answers` on a `tells` promises a channel that never exists.
         def refuse_wrong_words!(outbound)
           if outbound
             unless @emits.empty?
@@ -170,21 +109,8 @@ module Hecks
           end
         end
 
-        # Evaluates one operation block against a fresh builder and returns what it built.
-        #
-        # `private` above (scoping the instance methods between it and here)
-        # doesn't reach a singleton method — correctly so: `.build` is this
-        # builder's real public entry point (DomainPortBuilder calls it),
-        # never meant to be private.
-        #
-        # @param name [String] the operation's name
-        # @param to [Symbol, String, Module, nil] the aggregate the operation routes to, or nil
-        # @param owner [String, nil] name of the aggregate the enclosing port is declared on
-        # @param direction [Symbol] `:inbound` for `operation`/`tells`, `:outbound` for `asks`
-        # @yield the operation body, evaluated with the builder as `self`; may be omitted
-        # @return [Bluebook::PortOperation] the built operation
-        # @raise [Bluebook::DSL::Malformed] if the body uses the other direction's words, omits
-        #   the ones its own direction requires, or uses a word the grammar does not admit
+        # Evaluates one operation block against a fresh builder and returns what it built;
+        # `private` above doesn't reach this singleton method, since `.build` is the real entry.
         # rubocop:disable-next Lint/IneffectiveAccessModifier
         def self.build(name, to: nil, owner: nil, direction: :inbound, &block)
           builder = new(name, to: to, owner: owner, direction: direction)