hecks 2.7.0 → 2.9.0

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

@@ -3,211 +3,34 @@ require_relative "bootstrap_table"
 module Hecks
   module Bluebook
     module DSL
-      # Item #13's full metaprogrammed dispatch — slices 1-2 of 4, whole-
-      # project table-unification survey. WordGate (the first slice,
-      # already shipped) only checks a word's admissibility; this module
-      # executes the safe, mechanical subset of what a word actually
-      # does, read live off the same self-hosted grammar table — so a
-      # builder method for one of these words no longer needs to be
-      # hand-written at all. Called from `WordGate#method_missing`'s own
-      # "admitted here, no builder method for it yet" branch, so it only
-      # ever sees a word whose (context, word) pair the grammar already
-      # admits.
-      #
-      # ## What is covered
-      #
-      # Scope, deliberately narrow and verified word-by-word — a full
-      # audit read every real Ruby builder method's own source before
-      # any of this was written, not inferred from the table's shape
-      # alone (which fooled a first pass: `ReadModelBuilder#group_by`/
-      # `#include` look like plain fills from `kind`/`fills` alone, but
-      # actually wrap their arguments in a Hash/tuple). What's covered:
-      #
-      #   - a single, non-variadic, positional Argument row whose value
-      #     is stored with nothing beyond a uniform, kind-driven
-      #     coercion (`COERCE_BY_KIND`) — or, for `kind: "text"`, no
-      #     coercion at all when the row's own `coerce: "false"` says so
-      #     (six real, audited exceptions: `.to_s` on an actual String
-      #     is a same-object no-op for every real corpus use, but a
-      #     genuine behavior change for a direct Ruby API call passing
-      #     something else)
-      #   - a scalar assign (`@ivar = value`) or list append (`@ivar <<
-      #     value`), chosen by whether the ivar `fills:` names is
-      #     already an Array at call time (every candidate's own
-      #     `initialize` pre-populates its accumulating ivars as `[]` —
-      #     read live, not assumed)
-      #   - a zero-argument word, either (a) one of several sibling
-      #     Keyword rows in the same context sharing the same `fills:`
-      #     target — derives its own stored value from its own word
-      #     name as a symbol (`core`/`generic`/`supporting` all fill
-      #     `classification`), or (b) the only Keyword row filling its
-      #     own `fills:` target — a bare marker, stores literal `true`
-      #     (`ReadModel#count`)
-      #   - an OPENS_BLOCK word named in `SAFE_OPENS_BLOCK` below,
-      #     verified to do nothing beyond "build the child, instance_
-      #     eval the block against it, append the result" — see that
-      #     constant's own comment
-      #   - (slice 2) a single-fill word whose row also names a `blank_
-      #     message:` — raises that exact Malformed text if the coerced
-      #     value is blank, before storing it, matching a real hand-
-      #     written guard exactly (`Translation#retired`/
-      #     `TranslationAggregate#drop`, the only two words in the whole
-      #     grammar with this precise shape — `required: "true"` alone
-      #     only gates Ruby's own arity, never a present-but-blank
-      #     value, and most `required: "true"` words do not raise on
-      #     blank, so this needed a real per-row signal, not an
-      #     assumption from `required:` alone)
-      #
-      # ## What stays hand-written
-      #
-      # Explicitly out of this slice (found live, during the audit, not
-      # assumed) — stays hand-written, unaffected, until a later slice's
-      # own new table columns (`gated_by:`/`calls:`) can name
-      # what it really does: variadic accumulation with a real transform
-      # (`attaches_to`); source-block extraction (`ensures`, `where`);
-      # Struct/Hash-wrapping (`limit`, `group_by`, `rekey`); a guard
-      # clause not reducible to a plain blank-check (`role`'s own "raise
-      # if already set" uniqueness gate — a genuinely different shape
-      # from `retired`/`drop`'s own blank-check, needing its own
-      # design); a dynamically-built refusal message rather than one
-      # fixed string (`TranslationAggregateBuilder#unresolved` — real
-      # branching logic choosing between several message shapes, not a
-      # simple "always refuses" flag; belongs with `calls:`, slice 4,
-      # where a table row can name the real Ruby helper that already
-      # builds it); a side effect beyond storage (`uses_framework`,
-      # `uses_embryonaut_bluebook`); an opens-block word threading extra
-      # constructor args to its child (`asks`/`tells`/`operation`,
-      # `Bluebook#aggregate`, `Translation#aggregate`) or doing anything
-      # beyond a bare fold after building (`Aggregate#policy`'s stamp,
-      # `Aggregate#value_object`'s flatten, `Hecksagon#port`'s resolver-
-      # swap-and-branch); the deferred-build queue pattern (`Aggregate`/
-      # `Entity`'s own `command`/`entity`/`query`); the shadow_parsing?-
-      # gated words (`has_many`/`has_one`/`belongs_to`/`then_set`/
-      # `trigger`/`dispatch`/`one_of` — each delegates to its own
-      # `legacy_*` method under `MetaValidator.shadow_parsing?`, else
-      # refuses; a genuinely different two-branch shape per word, closer
-      # to `calls:`'s own territory than a simple fill); and every
-      # `File`-context word (routes through `Runtime.current_registry`,
-      # a side effect this module has no business performing).
-      #
-      # ## Words that look table-safe and are not
-      #
-      # Two further, different reasons a word can look table-safe and
-      # still be excluded, both found live rather than assumed:
-      #   - Bootstrap reachability. `WordGate`'s own gate steps aside
-      #     entirely while `MetaValidator.bootstrapping?` (the meta-
-      #     domain's own circularity — its grammar table doesn't exist
-      #     yet to read), and `load_grammar_into` loads real `.port`/
-      #     `.adapter` files, plus every core `.bluebook` chapter, during
-      #     that exact window. Any word those files actually call (found
-      #     to be nearly every common one — `vision`/`core`/`generic`/
-      #     `supporting`/`description`/`goal`/`emits`/`role`/`identified_
-      #     by` describe literally every self-hosted aggregate/command)
-      #     has no working method to fall back on if its hand-written
-      #     `def` is removed — `super` from `WordGate#method_missing`
-      #     just raises `NoMethodError`. `PortBuilder`/`AdapterBuilder`/
-      #     `BluebookBuilder` turned out to be entirely off-limits to
-      #     this slice for exactly this reason, confirmed by cold-
-      #     booting `MetaValidator.grammar_registry` after each
-      #     candidate removal, not assumed safe from reading the table
-      #     alone.
-      #   - A conflicting hand-written `method_missing`. `WorldBuilder`
-      #     and `HecksagonBuilder` each define their own `method_missing`
-      #     directly on the class (for genuinely open-ended settings/
-      #     collector verbs) — a method defined directly on a class always
-      #     wins over one from an included module in Ruby's own method
-      #     resolution, so `WordGate`'s (and this module's) own
-      #     `method_missing` never runs for their builders at all. Their
-      #     own candidate words (`realm`/`latest`, `subscribe`) stay
-      #     hand-written for this structural reason, independent of
-      #     whether their own behavior would otherwise qualify.
+      # Executes a grammar-admitted (context, word) pair straight off the DSL's own table when
+      # its row matches one of a few verified-safe shapes; anything else falls through unchanged.
       module GenericDispatch
         NOT_HANDLED = Object.new.freeze
 
         COERCE_BY_KIND = { "text" => :to_s, "symbol" => :to_sym }.freeze
 
-        # (context, word) OPENS_BLOCK pairs verified, by reading every
-        # real Ruby method, to do nothing beyond building the child and
-        # appending it — see this file's own header for the full account
-        # of what was excluded and why. Value: the ivar the built child
-        # is appended into. Not derivable from `fills:` — every one of
-        # these Keyword rows carries `fills: ""`; the append target is
-        # implicit in the hand-written code today, never named by the
-        # table at all, so this is the one place slice 1 hand-names a
-        # fact the table doesn't yet carry, rather than guessing a
-        # pluralization rule that would silently mismatch a future word.
+        # Not derivable from `fills:` (these rows all carry `fills: ""`) — the append target
+        # for each opens-block word must be named here explicitly.
         SAFE_OPENS_BLOCK = {
           %w[Bluebook policy]          => :policies,
           %w[Bluebook process_manager] => :process_managers,
           %w[Bluebook read_model]      => :read_models
         }.freeze
 
-        # `WordGate#method_missing`'s own bootstrap-window fallback,
-        # consulted only while `MetaValidator.bootstrapping?` (the real
-        # table doesn't exist yet to read `keyword[:calls]` from). Names
-        # the same (context, word) -> method pairs the real table's own
-        # `calls:` column carries — every live row, projected ahead of
-        # time into the committed lib/hecks/bluebook/dsl/bootstrap_table.rb
-        # (bin/project_bootstrap_table, pinned by spec/bootstrap_table_spec.rb).
-        #
-        # Every row is carried, rather than a hand-kept subset checked for
-        # bootstrap-reachability by grepping the core chapters. Carrying
-        # all of them costs nothing: a builder with its own `def` never
-        # reaches `method_missing`, and one without gains the same dispatch
-        # it gets once bootstrapping ends. `["Type", word]` rows still cover
-        # `list_of`/`one_of` in an attribute's type position for every
-        # calling context (see `word_gate_dispatch`'s own header).
+        # Consulted only while `MetaValidator.bootstrapping?`, before the real grammar table
+        # exists to read `calls:` from; every row is carried since carrying them costs nothing.
         BOOTSTRAP_CALLS_FALLBACK = BootstrapTable::CALLS
 
         module_function
 
-        # Reports whether `try` would execute a (context, word) pair, without executing anything.
-        #
-        # **The static predicate** — does this (context, word) pair fall
-        # within this slice's own verified scope, without executing
-        # anything? The same row-shape checks `try` itself runs before
-        # ever touching a real argument, shared so a conformance spec
-        # (which has no real call, no real builder instance) can ask the
-        # same question `method_missing` answers live.
-        #
-        # @param context [String] the grammar context, a builder's `GRAMMAR_CONTEXT` such as
-        #   `"Aggregate"`, or `"Type"`
-        # @param word [String] the DSL word; a Symbol never matches a row
-        # @param rows [Hash{Symbol => Array<Hash{Symbol => String}>}] the grammar table, with
-        #   `:keywords` and `:arguments` row lists; defaults to the live self-hosted table
-        # @return [Boolean] true when `try` would execute the word rather than answer `NOT_HANDLED`
+        # Whether `try` would execute this (context, word) pair, without executing anything.
         def handles?(context, word, rows: MetaValidator::SyntaxBoot.call)
           !shape_for(context, word, rows).nil?
         end
 
-        # Executes a grammar-admitted word straight off the table when its row shape is one of
-        # the four verified safe ones.
-        #
-        # `NOT_HANDLED` for anything outside this slice's own verified
-        # scope — the caller (`WordGate#method_missing`) falls through
-        # to its own existing "not yet implemented" refusal, unchanged,
-        # the exact same message a word not yet migrated to any slice
-        # already gets today. A real `ArgumentError` — matching what a
-        # hand-written method of the same arity would raise — for a
-        # call whose shape the grammar admits but whose actual argument
-        # count doesn't match; never a silent wrong answer.
-        #
-        # @param builder [Bluebook::DSL::WordGate] the builder instance the word was called on
-        # @param context [String] the grammar context the word was admitted under
-        # @param word [String] the DSL word being executed
-        # @param args [Array<Object>] the call's positional arguments
-        # @param kwargs [Hash{Symbol => Object}] the call's keyword arguments
-        # @param block [Proc, nil] the block given to the word, if any
-        # @param rows [Hash{Symbol => Array<Hash{Symbol => String}>}] the grammar table, with
-        #   `:keywords` and `:arguments` row lists
-        # @return [Object] what executing the word produced — the target method's own result
-        #   for a `calls:` row, otherwise the stored value or the list appended to — or
-        #   `NOT_HANDLED` when the word is outside the verified scope
-        # @raise [ArgumentError] if the word is table-executed and the positional argument count
-        #   does not match what its row admits
-        # @raise [Bluebook::DSL::Malformed] if a single-fill row names a `blank_message:` and the
-        #   value is blank, or the `calls:` target itself refuses the declaration
-        # @raise [Runtime::WiringError] if `shape_for` names a kind this method has no arm for
+        # Executes a table-admitted word via the shape `shape_for` found for it, or returns
+        # NOT_HANDLED so the caller can fall back to its own "not yet implemented" refusal.
         def try(builder, context, word, args, kwargs, block, rows)
           shape = shape_for(context, word, rows)
           return NOT_HANDLED unless shape
@@ -218,40 +41,18 @@ module Hecks
           when :zero_arg      then try_zero_arg(builder, shape[:keyword], args)
           when :single_fill   then try_single_fill(builder, shape[:fills], shape[:argument], args, kwargs)
           else
-            # `shape_for` names exactly four kinds and this case
-            # matches all four — a backstop against the day a fifth is
-            # added there without a matching arm here. Falling through
-            # silently would return bare `nil` from what the caller
-            # (`WordGate#method_missing`) reads as "handled" (anything
-            # other than NOT_HANDLED counts), so a self-hosted DSL word
-            # would silently execute as a no-op instead of raising the
-            # same "not yet implemented" refusal a genuinely unmigrated
-            # word already gets.
+            # Backstop: `shape_for` names exactly four kinds; falling through would return nil,
+            # which the caller reads as "handled", silently turning the word into a no-op.
             raise Runtime::WiringError,
                   "no dispatcher handles shape #{shape[:kind].inspect} — add one before shape_for can produce it"
           end
         end
 
-        # Classifies a (context, word) pair into the table-executable shape its rows describe.
-        #
-        # The one place row shape is judged — returns a small Hash naming
-        # which of the four safe shapes (context, word) is, or `nil` if
-        # it falls outside this slice's own verified scope. No argument
-        # values are read here; this only ever looks at the table.
+        # Classifies a (context, word) pair into one of the four table-executable shapes, or
+        # nil when it falls outside this module's verified scope.
         #
-        # An early-return classification chain: each `return` depends on
-        # locals (`calls`, `fills`, `arguments`, `arg`) computed by the
-        # checks before it. Splitting per shape would mean re-deriving or
-        # threading those locals across method boundaries for a
-        # classification that is only ever read top-to-bottom once, here.
-        #
-        # @param context [String] the grammar context to look the word up under
-        # @param word [String] the DSL word; retired rows never match
-        # @param rows [Hash{Symbol => Array<Hash{Symbol => String}>}] the grammar table, with
-        #   `:keywords` and `:arguments` row lists
-        # @return [Hash{Symbol => Object}, nil] `:kind` is `:calls_through` (with `:calls`, the
-        #   target method name), `:opens_block` or `:zero_arg` (with `:keyword`, the row), or
-        #   `:single_fill` (with `:fills` and `:argument`); nil when the word is out of scope
+        # Early-return chain: each check depends on locals from the ones before it, read once
+        # top-to-bottom; splitting per shape would just re-thread the same locals across methods.
         # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def shape_for(context, word, rows)
           keyword = rows[:keywords].find { |k| k[:context] == context && k[:word] == word && k[:status] != "retired" }
@@ -277,44 +78,14 @@ module Hecks
           { kind: :single_fill, fills: fills, argument: arg }
         end
 
-        # Forwards a word's whole call to the builder method its row's `calls:` column names.
-        #
-        # `keyword[:calls]` names a real Ruby method whose whole call —
-        # every positional, every kwarg, the block, all of it — forwards
-        # here unchanged. No argument-shape interpretation at all,
-        # deliberately: the target method (`AttributeCollector#
-        # attribute_impl`, etc.) already does its own, real, hand-
-        # written argument handling; this is a pure, transparent `send`,
-        # the lowest-risk possible shape for a word whose own logic is
-        # too complex to re-derive from the table (type-quoting refusal,
-        # closed-set synthesis, pattern validation, ...).
-        #
-        # @param builder [Bluebook::DSL::WordGate] the builder instance to send the call to
-        # @param calls [String, Symbol] the target method's name, such as `"attribute_impl"`
-        # @param args [Array<Object>] positional arguments, forwarded unchanged
-        # @param kwargs [Hash{Symbol => Object}] keyword arguments, forwarded unchanged
-        # @param block [Proc, nil] the block, forwarded unchanged
-        # @return [Object] whatever the target method returns
-        # @raise [Bluebook::DSL::Malformed] if the target method refuses the declaration
+        # Forwards a word's whole call, unchanged, to the builder method its row's `calls:`
+        # names — no argument-shape interpretation; the target method already does its own.
         def try_calls_through(builder, calls, args, kwargs, block)
           builder.send(calls, *args, **kwargs, &block)
         end
 
-        # Builds a child construct from a block-opening word and appends it to the builder's list.
-        #
-        # @param builder [Bluebook::DSL::WordGate] the builder whose list receives the child
-        # @param keyword [Hash{Symbol => String}] the word's Keyword row; `:opens` names the
-        #   child builder class without its `Builder` suffix, and the pair of `:context` and
-        #   `:word` must be a `SAFE_OPENS_BLOCK` key
-        # @param args [Array<Object>] the call's positional arguments; exactly one, the child's
-        #   name
-        # @param kwargs [Hash{Symbol => Object}] the call's keyword arguments
-        # @param block [Proc, nil] the child's body, evaluated against the child builder
-        # @return [Array<Object>, Object] the builder's list with the built child appended, or
-        #   `NOT_HANDLED` when any keyword argument was given
-        # @raise [ArgumentError] if the call does not carry exactly one positional argument
-        # @raise [KeyError] if the row's context and word are not in `SAFE_OPENS_BLOCK`
-        # @raise [Bluebook::DSL::Malformed] if the child builder refuses its own body
+        # Builds a child construct from a block-opening word and appends it to the builder's
+        # list named by its row in `SAFE_OPENS_BLOCK`.
         def try_opens_block(builder, keyword, args, kwargs, block)
           return NOT_HANDLED unless kwargs.empty?
 
@@ -331,14 +102,6 @@ module Hecks
         end
 
         # Stores a zero-argument word's value into the instance variable its row's `fills:` names.
-        #
-        # @param builder [Bluebook::DSL::WordGate] the builder whose instance variable is set
-        # @param keyword [Hash{Symbol => String}] the word's Keyword row, read for `:context`,
-        #   `:fills` and `:word`
-        # @param args [Array<Object>] the call's positional arguments, which must be empty
-        # @return [Symbol, true] the stored value: the word itself as a Symbol when sibling words
-        #   share the same `fills:` target (`core`/`generic`/`supporting`), otherwise `true`
-        # @raise [ArgumentError] if any positional argument was given
         def try_zero_arg(builder, keyword, args)
           raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0)" unless args.empty?
 
@@ -352,19 +115,7 @@ module Hecks
         end
 
         # Coerces a word's one positional argument and stores it, appending when the target
-        # instance variable already holds an Array and assigning otherwise.
-        #
-        # @param builder [Bluebook::DSL::WordGate] the builder whose instance variable is filled
-        # @param fills [String] the instance variable's name, without the `@`
-        # @param arg [Hash{Symbol => String}] the word's single Argument row, read for `:kind`,
-        #   `:coerce` and `:blank_message`
-        # @param args [Array<Object>] the call's positional arguments; exactly one
-        # @param kwargs [Hash{Symbol => Object}] the call's keyword arguments
-        # @return [Object] the stored value, or the Array it was appended to, or `NOT_HANDLED`
-        #   when any keyword argument was given
-        # @raise [ArgumentError] if the call does not carry exactly one positional argument
-        # @raise [Bluebook::DSL::Malformed] if the row names a `blank_message:` and the coerced
-        #   value is blank
+        # ivar already holds an Array and assigning otherwise.
         def try_single_fill(builder, fills, arg, args, kwargs)
           return NOT_HANDLED unless kwargs.empty?
 

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

@@ -2,13 +2,8 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses a `.hecksagon` file's top-level DSL block into a `Hecksagon`
-      # — a domain's own wiring: which adapter binds to which verb
-      # (`persisted_by`, `projected_by`, ...), which framework/vendored
-      # bluebooks it attaches, which external events it subscribes to, and
-      # its bare chapter-root port. Kept separate from the bluebook itself
-      # (the domain's own declared model) because wiring is an operational
-      # decision, not a fact the domain states about itself.
+      # Parses a `.hecksagon` file's DSL block into a Hecksagon: a domain's adapter bindings,
+      # framework/vendored attachments and subscriptions — wiring, not part of the bluebook.
       class HecksagonBuilder
         GRAMMAR_CONTEXT = "Hecksagon".freeze
 
@@ -20,7 +15,6 @@ module Hecks
 
         attr_reader :binds, :subscriptions, :framework_members, :vendored_bluebooks
 
-        # @param domain [String] name of the domain whose wiring this hecksagon declares
         def initialize(domain)
           @domain             = domain
           @binds              = []
@@ -31,168 +25,59 @@ module Hecks
           @translates         = []
         end
 
-        # Marks THIS chapter as a bounded context — a consumer-owned chapter
-        # that `uses_framework` / `uses_embryonaut_bluebook` will not load.
-        # Framework and vendored packages get the mark automatically from
-        # those words; they never write `bounded` in their own bluebooks.
-        # A bounded chapter wraps in its own module (no Object shortcut)
-        # and must declare at least one `translates` ACL or boot refuses.
-        #
-        # @return [Boolean] true
+        # Marks this chapter as a bounded context; framework/vendored attachments set it too.
+        # Must declare at least one `translates` ACL or boot refuses.
         def bounded
           @bounded = true
         end
 
-        # Subscribes this hecksagon to an event it takes from outside the domain's own bluebook.
-        #
-        # @param event [String, Symbol] the external event's name
-        # @return [Array<String>] every subscription declared so far, this one last
+        # Subscribes to an event from outside this domain's own bluebook.
         def subscribe(event) = @subscriptions << event.to_s
 
-        # Attaches a framework member to this domain and loads it into the current registry.
-        #
-        # A framework/ member this domain wants attached —
-        # Governance, Identity, whatever else lands beside them.
-        # Attaching one is a wiring decision, the same kind `persisted_by`/
-        # `projected_by` already are, so it lives here rather than as a
-        # fact stated in the domain's own bluebook. Recorded onto this
-        # hecksagon, the same way `subscribe` records onto its own
-        # `subscriptions` — and loads the member's bluebook then its own
-        # hecksagon into whatever registry this one is loading into, see
-        # `Framework.load!`.
-        #
-        # @param name [String, Symbol] the member's name, such as `"Governance"`
-        # @return [Boolean, nil] true when this call loaded the member's bluebook, nil when the
-        #   current registry already held it
-        # @raise [Runtime::WiringError] if no framework member has that name
+        # Attaches a framework member (e.g. Governance) and loads it into the current registry.
         def uses_framework(name)
           @framework_members << name.to_s
           Hecks::Framework.load!(name)
-          # Automatic bounded mark — the framework member is a bounded
-          # context; the consumer's sibling `Hecks.hecksagon "Name"` is
-          # the anti-corruption layer. Not written in the framework
-          # bluebook itself.
+          # Marks the framework member as bounded; the consumer's own hecksagon is the
+          # anti-corruption layer.
           Hecks.current_registry&.mark_bounded(name.to_s)
         end
 
         # Attaches a vendored embryonaut bluebook to this domain and loads its files into the
-        # current registry.
-        #
-        # A vendored, external bluebook this domain wants attached — same
-        # wiring-decision shape `uses_framework` already is, one level
-        # further out: not a member shipped inside hecks's own lib/,
-        # but a separate package (embryonaut_bluebooks) vendored into this
-        # project's own checkout. See EmbryonautBluebook's own header for
-        # the full reasoning on why its root can't be a fixed constant the
-        # way Framework::ROOT is, and for the recovery provenance.
-        #
-        # Recorded onto @vendored_bluebooks, same shape `uses_framework`
-        # already gives @framework_members — a separate list on purpose:
-        # `framework_members` is load-bearing for `refuse_ungoverned_roles!`
-        # (`Registry::Verification`) and for Governance's own attachment
-        # check; conflating the two would make a vendored bluebook attachment
-        # satisfy a Governance check it has nothing to do with.
-        #
-        # @param name [String, Symbol] the vendored package's directory name under
-        #   `vendor/embryonaut_bluebooks/`
-        # @return [Array<String>, nil] paths of the `.bluebook` files this call loaded, or nil
-        #   when the current registry already held the bluebook
-        # @raise [Runtime::WiringError] if the current registry has no root to vendor from, or
-        #   no vendored bluebook of that name exists under it
+        # registry. Recorded separately from @framework_members, which is load-bearing for
+        # governance checks.
         def uses_embryonaut_bluebook(name)
           @vendored_bluebooks << name.to_s
           Hecks::EmbryonautBluebook.load!(name)
-          # Automatic bounded mark — same as `uses_framework`. The
-          # package's directory name Pascal-cases to the chapter
-          # (`"membership"` → `Membership`).
+          # Marks the chapter bounded, same as `uses_framework`; the directory name Pascal-cases
+          # to the chapter name (`"membership"` → `Membership`).
           Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
         end
 
-        # Declares a port at the hecksagon's root and attaches it to the registered bluebook.
-        #
-        # The primary port, bare at the root — belongs to the chapter as a
-        # whole, not one aggregate. `BindingProxy#port` is the aggregate-
-        # scoped sibling (`Payments::Payment.port("Gateway") do ... end`);
-        # this is what's left when a port isn't about any one record. The
-        # bluebook must already be built and registered, since a hecksagon
-        # loads after its bluebook, and this attaches to that real, final
-        # object directly rather than building a second copy MetaValidator
-        # would have to know how to reconstruct.
-        #
-        # Answers the `port` word through the table's `calls:` column —
-        # item #13's full metaprogrammed dispatch (slice 5). Not
-        # bootstrap-reachable (checked directly — no core/attached chapter
-        # declares a Hecksagon of its own). Reached through `WordGate`'s
-        # `word_gate_dispatch`, called explicitly below since
-        # `HecksagonBuilder`'s own class-level `method_missing` (the
-        # open-verb catch-all beneath this) always wins over the module's —
-        # see `word_gate.rb`'s own header for the full mechanism.
-        #
-        # @param name [String] the port's name
-        # @yield the port body, evaluated against a `DomainPortBuilder`: either `verb`/`signal`
-        #   or `operation`/`tells`/`asks` blocks
-        # @return [Bluebook::Port, Bluebook::DomainPort] the built port: a verb-shaped `Port`
-        #   registered on the current registry, or a `DomainPort` attached to the bluebook
-        # @raise [Bluebook::DSL::Malformed] if the current registry holds no bluebook for this
-        #   domain, or the body declares both a verb and operations, neither, or an operation
-        #   the port grammar refuses
+        # Declares a port at the hecksagon's root — the chapter as a whole, not one aggregate.
         def port_impl(name, &block)
           bluebook_ir = Hecks.current_registry.bluebook(@domain) or
             raise Malformed, "#{@domain} declares no such bluebook — a port needs one to belong to"
 
-          # See BindingProxy#port's own comment on why this resolver swap is
-          # needed — ConstShim's active resolver is one global for the whole
-          # dynamic extent, currently this file's own BindingProxy-minting
-          # one, which would turn a bare constant inside an operation's
-          # `reference_to`/`attribute` into another BindingProxy instead of
-          # a name.
+          # Swaps the active ConstShim resolver to plain passthrough — without it a bare constant
+          # inside `reference_to`/`attribute` would resolve to a BindingProxy instead of a name.
           built = ConstShim.with(->(const) { const }) { DomainPortBuilder.build(name, &block) }
 
-          # See BindingProxy#port's own comment on the same branch — a
-          # `verb`-shaped port is a plain `Port`, registered the same
-          # way `Hecks.port`'s top-level method already does, not attached
-          # to this bluebook's own IR the way an operations-shaped
-          # `DomainPort` is.
+          # A verb-shaped port is a plain `Port`, registered like `Hecks.port`'s top-level method,
+          # not attached to this bluebook's IR the way an operations-shaped `DomainPort` is.
           return Hecks.current_registry.add_port(built) if built.is_a?(Port)
 
           bluebook_ir.add_port(built)
         end
 
-        # A TRANSLATION BOUNDARY, NOT A BUSINESS RULE — `translates "Name"
-        # do on Foreign::Domain::SomeEvent; trigger Local.Command; end`
-        # builds the EXACT SAME `Policy` a `policy` block inside this
-        # domain's own `.bluebook` would (same `on_impl`/`trigger_impl`,
-        # same `PolicyInterpreter` runtime — reusing `PolicyBuilder`
-        # directly, zero new runtime semantics). What's new is only WHERE
-        # it can be written: a cross-domain reaction is a wiring/context-
-        # mapping decision (this chapter conforming to a foreign chapter's
-        # published event), the same kind of decision `port`/
-        # `uses_framework` already are — not a fact this domain's own
-        # model states about itself, which `policy` (inside the bluebook)
-        # remains the right word for.
-        #
-        # MUST BE A BLOCK, not `translates Event, into: Command` — a flat
-        # call's arguments are evaluated eagerly, under THIS builder's own
-        # `ConstShim` resolver (`BindingProxy.namespace`, set up by
-        # `self.build` below), which mints a `BindingProxy` INSTANCE per
-        # segment and cannot answer a further `::` (it is not a Module) —
-        # a multi-segment reference like `Deploy::Tenant::TenantProvisioned`
-        # would raise before this method ever ran. `port_impl`'s own
-        # `ConstShim.with(->(const) { const })` swap only works because
-        # its own callers never pass a multi-segment bare constant as an
-        # eagerly-evaluated argument — everything of that shape lives
-        # inside ITS block, evaluated later, under the swapped resolver.
-        # A block defers evaluation the same way; a flat call cannot.
+        # A cross-domain reaction, built as the same `Policy` an in-bluebook `policy` block would.
+        # Must be a block — the eager const resolver here can't handle multi-segment references.
         def translates(name, &block)
           bluebook_ir = Hecks.current_registry.bluebook(@domain) or
             raise Malformed, "#{@domain} declares no such bluebook — translates needs one to attach its reaction to"
 
-          # SAME RESOLVER BluebookBuilder ITSELF uses for a `policy`
-          # block's own `on`/`trigger` (bluebook_builder.rb) — a
-          # `ScopedConstant`, not the bare passthrough `port_impl` swaps
-          # to, because `on`/`trigger` here take genuinely multi-segment
-          # references (`Deploy::Tenant::TenantProvisioned`), not a
-          # single-segment type name.
+          # Same resolver `policy` blocks use for `on`/`trigger` — a ScopedConstant, not the bare
+          # passthrough `port_impl` swaps to, since these take multi-segment references.
           resolver = ->(const) { ConstShim::ScopedConstant.for(const) }
           built = ConstShim.with(resolver) { PolicyBuilder.build(name, &block) }
 
@@ -201,58 +86,18 @@ module Hecks
         end
 
         # Assembles the collected binds, subscriptions and attachments into a `Hecksagon`.
-        #
-        # No ungoverned-role check here — see
-        # Registry::Verification#refuse_ungoverned_roles!. It lives outside
-        # per-block `build`, alongside `environment:`
-        # (Runtime::Loader.boot's comment has the provenance): a domain
-        # split across multiple hecksagon blocks (base + an
-        # `environments/<name>.hecksagon` overlay) would have every
-        # block but the one declaring `uses_framework "Governance"`
-        # refused here, even though `Registry#add_hecksagon` merges them
-        # into one Hecksagon before anything ever dispatches against it.
-        # Checking the merged result once, at verify! time — after every
-        # file for this domain has loaded — is both more permissive (no
-        # need to repeat `uses_framework` in every file) and strictly
-        # more correct (a check against an incomplete, not-yet-merged
-        # hecksagon can never see the real final shape).
-        #
-        # @return [Bluebook::Hecksagon] this block's wiring, which `Registry#add_hecksagon` merges
-        #   with any other block declared for the same domain
+        # No ungoverned-role check here — it runs once on the merged result at verify! time.
         def build
           Hecksagon.new(domain: @domain, binds: @binds, subscriptions: @subscriptions,
                         framework_members: @framework_members, vendored_bluebooks: @vendored_bluebooks,
                         bounded: @bounded, translates: @translates)
         end
 
-        # Records any verb the grammar does not own as a domain-wide bind to the named adapter.
-        #
-        # **Domain-level default binds** — `persisted_by "Heki"` bare, at the top
-        # of a hecksagon block, applies to every aggregate in this domain
-        # that doesn't declare its own override. Mirrors `BindingProxy`'s own
-        # `method_missing` one level down (`aggregate:` filled in there,
-        # `nil` here) — generic over verb name, not hardcoded to
-        # `persisted_by`/`projected_by` specifically, so any future verb
-        # gets a domain-level default for free too. See `Hecksagon#bind_for`
-        # for the fallback lookup this feeds.
-        #
-        # @param verb [Symbol] the word called, such as `:persisted_by`
-        # @param args [Array<Object>] positional arguments; the first names the adapter
-        # @param kwargs [Hash{Symbol => Object}] keyword arguments; `:role` is kept on the bind
-        # @yield an optional block, called once after the bind is recorded
-        # @return [Object] this builder after recording a bind, or the grammar word's own result
-        #   when `verb` is one the `Hecksagon` grammar admits
-        # @raise [NoMethodError] if `verb` is no grammar word and names no adapter
-        # @raise [Bluebook::DSL::Malformed] if the grammar admits `verb` only in another context,
-        #   or admits it here and its implementation refuses the declaration
+        # Records any verb the grammar doesn't own as a domain-wide default bind, e.g. bare
+        # `persisted_by "Heki"` at the top of a block, applied unless an aggregate overrides it.
         def method_missing(verb, *args, **kwargs, &block)
-          # A closed-set grammar word (`port`, today) gets first refusal
-          # — item #13's full metaprogrammed dispatch (slice 5); see
-          # `WordGate#word_gate_dispatch`'s own header for why this class
-          # needs to call it explicitly rather than including it the
-          # ordinary way. Only once that says "not admitted" does the
-          # genuinely open-ended `persisted_by "Heki"`-style bind
-          # vocabulary below get a turn.
+          # Grammar words (like `port`) get first refusal via explicit dispatch; only when that's
+          # not admitted does the open-ended `persisted_by`-style bind vocabulary below apply.
           result = word_gate_dispatch(verb, args, kwargs, block)
           return result unless result.equal?(WordGate::NOT_ADMITTED)
 
@@ -267,14 +112,6 @@ module Hecks
 
         # Evaluates a `Hecks.hecksagon` block with bare `Domain::Aggregate` constants resolving to
         # bind-collecting proxies, and returns the wiring it declared.
-        #
-        # @param domain [String] name of the domain being wired
-        # @yield the hecksagon body, evaluated with the builder as `self`; may be omitted
-        # @return [Bluebook::Hecksagon] the declared wiring
-        # @raise [Bluebook::DSL::Malformed] if a `port` names no registered bluebook or aggregate,
-        #   or declares a shape the port grammar refuses
-        # @raise [Runtime::WiringError] if `uses_framework` or `uses_embryonaut_bluebook` names
-        #   something that cannot be found
         def self.build(domain, &block)
           builder  = new(domain)
           resolver = ->(name) { BindingProxy.namespace(name, builder.binds) }