hecks 1.3.0 → 1.5.0

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

@@ -16,6 +16,10 @@ module Hecks
         include RuleReference
         include WordGate
 
+        # @param name [String] the value object's name, as written after `value_object`
+        # @param owner_value_objects [Array<Bluebook::ValueObject>] the owning aggregate's other
+        #   value objects, built so far, that this one's `invariant` references may resolve
+        #   against
         def initialize(name, owner_value_objects: [])
           @name       = name
           @invariants = []
@@ -23,7 +27,7 @@ module Hecks
           @owner_value_objects = owner_value_objects
         end
 
-        # THE WRAPPER BLOCK IS GONE (ADR 0025, "Attributes" — "closed sets
+        # The wrapper block is gone (ADR 0025, "Attributes" — "closed sets
         # lose the wrapper block"). `member` lines are bare now, written
         # directly in the `value_object` body with no `one_of do ... end`
         # around them — `build`'s own `closed_set: @closed_set ||
@@ -39,24 +43,35 @@ module Hecks
         # use the inline form on one of its own attributes. One `one_of`
         # method now, not two.
         #
-        # LEGACY UNDER SHADOW-PARSING (S0a's own bridge) — frozen era text
+        # Legacy under shadow-parsing (S0a's own bridge) — frozen era text
         # still writes the block form (2 locations in
         # `examples/banking/data/eras/banking/1.bluebook`, duplicated once
         # more in that era's own archive copy), so `EraGuard.shadow_parse`
         # still needs to read it. `block_given?` is what tells the two
         # calling shapes apart: the type-position form
         # (`one_of("a", "b")`) never passes a block, only the wrapper does.
-        # RENAMED FROM `one_of` — item #13's full metaprogrammed dispatch
-        # (slice 5). SAME NAME as `AttributeCollector#one_of_impl`'s own
+        # Declares this value object as a closed set, either from bare values or (under
+        # shadow-parsing) a legacy `do ... end` wrapper of `member` lines.
+        #
+        # Answers the `one_of` word through the table's `calls:` column —
+        # item #13's full metaprogrammed dispatch
+        # (slice 5). Same name as `AttributeCollector#one_of_impl`'s own
         # — required for the `super(*values)` call below to keep
         # resolving; see that method's own comment. Reached directly
         # through its own "ValueObject"-context Keyword row (the
         # block-wrapper form has its own row, distinct from "Type"'s),
-        # not through the Type-position fallback this word's OTHER
+        # not through the Type-position fallback this word's other
         # context uses.
+        #
+        # @param values [Array<String, Symbol>] permitted values, given bare (no block); at
+        #   least one is required
+        # @yield a legacy `member` wrapper body; only read under shadow-parsing
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if given no values and no block, or a block outside
+        #   shadow-parsing
         def one_of_impl(*values, &block)
           unless block
-            # NO VALUES, NO BLOCK is the SCALAR spelling — nonsensical, not
+            # No values, no block is the scalar spelling — nonsensical, not
             # merely inert: it names a closed set with nothing in it. The
             # original block form caught this by a side effect (`@closed_set
             # = true` ran unconditionally, before the `if block`), and this
@@ -83,20 +98,27 @@ module Hecks
           instance_eval(&block)
         end
 
-        # RENAMED FROM `member` — item #13's full metaprogrammed dispatch
-        # (slice 4c). Bootstrap-reachable, in
-        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        # Declares one member row of a closed set, one value per attribute.
+        #
+        # Answers the `member` word through the table's `calls:` column —
+        # item #13's full metaprogrammed dispatch (slice 4c). Bootstrap-reachable, in
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
+        #
+        # @param fields [Hash{Symbol => Object}] each declared attribute's name mapped to this
+        #   member's value for it
+        # @return [Array<Hash{Symbol => Object}>] every member declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if `fields` is empty
         def member_impl(**fields)
           raise Malformed, "#{@name} declared an empty member" if fields.empty?
 
           @members << fields
         end
 
-        # NO BLOCK is a REFERENCE, not a fresh declaration — the same
+        # No block is a reference, not a fresh declaration — the same
         # move S10 already made for `CommandBuilder#given` (ADR 0025,
         # "a precondition shared across commands is declared once... a
         # command references it by name"), one level over: a rule
-        # shared across SIBLING value objects on the same aggregate,
+        # shared across sibling value objects on the same aggregate,
         # declared once, on the first one to need it. Real, live
         # redundancy this closes: `Account`'s own `Money`/`PositiveMoney`
         # both declared `invariant("a currency is a three-letter code")
@@ -105,9 +127,20 @@ module Hecks
         # the referencing value object's own build time, against
         # whatever sibling value objects the aggregate has already
         # built, the same ordering rule `given` carries.
-        # RENAMED FROM `invariant` — item #13's full metaprogrammed
-        # dispatch (slice 4b). Bootstrap-reachable, in
-        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        # Declares a rule this value object's own value must satisfy, or references one a sibling
+        # value object on the same aggregate already declared.
+        #
+        # Answers the `invariant` word through the table's `calls:` column —
+        # item #13's full metaprogrammed dispatch (slice 4b). Bootstrap-reachable, in
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
+        #
+        # @param description [String] the rule's description; also the name a sibling value
+        #   object references it by when no block is given
+        # @yield the predicate body; evaluated for its extracted source, never called directly
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if given a block whose source cannot be extracted or
+        #   uses a pattern construct engines disagree on, or given no block and no sibling value
+        #   object on this aggregate declares a rule with this description
         def invariant_impl(description, &predicate)
           return reference_named_invariant(description) unless predicate
 
@@ -119,7 +152,7 @@ module Hecks
 
         private
 
-        # PRIMITIVE 3 (RuleReference#resolve_sibling_scan) — see that
+        # Primitive 3 (RuleReference#resolve_sibling_scan) — see that
         # method's own comment for why this is a live scan, not a pool.
         def reference_named_invariant(description)
           verify_resolves_via!("invariant", "ValueObject", "sibling_scan")
@@ -134,6 +167,12 @@ module Hecks
 
         public
 
+        # Assembles the declared attributes, invariants and members into a `ValueObject`.
+        #
+        # @return [Bluebook::ValueObject] the built value object; `closed_set` is true when any
+        #   member was declared
+        # @raise [Bluebook::DSL::Malformed] if `one_of:` was declared on an attribute alongside
+        #   other attributes on the same value object
         def build
           if @inline_closed_set_field && attributes.size > 1
             raise Malformed,
@@ -149,6 +188,15 @@ module Hecks
           )
         end
 
+        # Evaluates a `value_object` block against a fresh builder and returns what it built.
+        #
+        # @param name [String] the value object's name
+        # @param owner_value_objects [Array<Bluebook::ValueObject>] the owning aggregate's other
+        #   value objects, for `invariant` references to resolve against
+        # @yield the value object body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::ValueObject] the built value object
+        # @raise [Bluebook::DSL::Malformed] if the body declares a rule extraction cannot read,
+        #   `one_of:` on more than one attribute, or uses a word the grammar does not admit
         def self.build(name, owner_value_objects: [], &block)
           builder = new(name, owner_value_objects: owner_value_objects)
           builder.instance_eval(&block) if block
@@ -157,15 +205,15 @@ module Hecks
 
         private
 
-        # THE NEW SPELLING — `attribute :name, String, one_of: %w[...]`,
-        # overriding `AttributeCollector`'s own refusal (every OTHER
-        # includer has no meaningful use for this). PRIVATE, like the
+        # **The new spelling** — `attribute :name, String, one_of: %w[...]`,
+        # overriding `AttributeCollector`'s own refusal (every other
+        # includer has no meaningful use for this). Private, like the
         # module's own version it overrides — it is a callback `attribute`
         # invokes on itself, never a word a bluebook author calls by name.
-        # Refuses a SECOND attribute naming one_of: on the same value
+        # Refuses a second attribute naming one_of: on the same value
         # object outright — a single-field set names exactly one field, by
         # construction; two would be structurally ambiguous about which
-        # field each member line belongs to. `build` refuses the OTHER
+        # field each member line belongs to. `build` refuses the other
         # half of that same rule (this attribute coexisting with unrelated
         # ones on a multi-field object).
         def install_inline_closed_set(field, values)

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

@@ -2,46 +2,49 @@ require_relative "generic_dispatch"
 module Hecks
   module Bluebook
     module DSL
-      # THE RUBY-SIDE `word_gate` (`rust/parser/src/parse/mod.rs`'s own,
+      # The Ruby-side `word_gate` (`rust/parser/src/parse/mod.rs`'s own,
       # read there first — this is the same job, one level up: Rust's own
-      # gate refuses a mistyped/inadmissible WORD directly, at the
-      # moment it reads a line of `.bluebook` SOURCE TEXT, before any
+      # gate refuses a mistyped/inadmissible word directly, at the
+      # moment it reads a line of `.bluebook` source text, before any
       # per-construct parsing runs. Ruby never lexes source text — a
-      # `.bluebook` file IS Ruby, so `given("x")` is ALREADY a real
+      # `.bluebook` file is Ruby, so `given("x")` is already a real
       # method call by the time any of this code runs, and Ruby's own
-      # method dispatch already refuses an ARITY mismatch on an
-      # EXISTING method for free. What Ruby's own dispatch does NOT do
-      # is consult the self-hosted grammar table AT ALL — a mistyped
+      # method dispatch already refuses an arity mismatch on an
+      # existing method for free. What Ruby's own dispatch does not do
+      # is consult the self-hosted grammar table at all — a mistyped
       # word (`giv3n("x")`) or a word used in the wrong context
       # (`identified_by` inside a `command` block) just raises Ruby's
       # own generic `NoMethodError`, naming nothing about what the
       # language actually admits. This module closes that gap.
       #
-      # `method_missing`/`respond_to_missing?` ONLY — a word this
+      # ## What reaches this module
+      #
+      # `method_missing`/`respond_to_missing?` only — a word this
       # builder class already answers with an ordinary `def` (or a
-      # shared mixin method like `AttributeCollector#attribute`) never
+      # method a shared mixin such as `AttributeCollector` defines) never
       # reaches this module at all; Ruby's own method lookup finds it
-      # first, and item #13's later slices haven't removed every one of
-      # those yet. This WAS "zero behavior change for every currently-
-      # valid line in the entire corpus" in its own first slice — since
-      # item #13's full metaprogrammed dispatch (slice 1, whole-project
-      # table-unification survey) started REMOVING the hand-written
-      # methods this module's own admissibility check used to defer to,
-      # some words now execute for real here too, via `GenericDispatch`
-      # — see that module's own header for exactly which ones, and the
-      # full account of what was verified before each was migrated. A
-      # mistyped or wrongly-contexted word still gets the same real,
-      # helpful, table-driven refusal Rust's own `word_gate` already
-      # gives, instead of Ruby's own generic `NoMethodError` — that half
-      # is genuinely unchanged.
+      # first, and not every word has had its hand-written method
+      # removed. A word the grammar admits whose builder has no
+      # hand-written method executes for real here, via `GenericDispatch`
+      # (item #13's full metaprogrammed dispatch, whole-project
+      # table-unification survey) — see that module's own header for
+      # exactly which ones, and the full account of what was verified
+      # before each was migrated. A mistyped or wrongly-contexted word
+      # gets the same real, helpful, table-driven refusal Rust's own
+      # `word_gate` already gives, instead of Ruby's own generic
+      # `NoMethodError`.
+      #
+      # ## `GRAMMAR_CONTEXT`
       #
       # `self.class::GRAMMAR_CONTEXT` — each including class names which
       # row of the self-hosted `Context` closed set it corresponds to
       # (`AggregateBuilder::GRAMMAR_CONTEXT = "Aggregate"`, etc.) — the
-      # SAME string `word_gate`'s own `context` parameter already is on
+      # same string `word_gate`'s own `context` parameter already is on
       # the Rust side, read off the identical table.
       #
-      # BOOTSTRAPPING GATED, the same reason `RuleReference#lookup`
+      # ## Bootstrapping
+      #
+      # Bootstrapping gated, the same reason `RuleReference#lookup`
       # already is (`rule_reference.rb`'s own comment has the full
       # story) — the meta-domain's own bootstrap calls dozens of
       # keywords on itself before its own grammar table exists to
@@ -52,28 +55,31 @@ module Hecks
       # is deliberately no fallback covering the whole ~200-row table —
       # that would defeat the entire point.
       #
-      # ONE NARROW EXCEPTION, added in item #13's full metaprogrammed
-      # dispatch (slice 3, whole-project table-unification survey):
-      # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, a SMALL, EXPLICIT
-      # table naming the same (context, word) -> method pairs the real
-      # `calls:` column would say once it exists — used ONLY for words
-      # BOTH migrated to the `calls:` shape AND bootstrap-reachable
-      # (`attribute`, today). This is the one place in this whole arc a
+      # One narrow exception (item #13's full metaprogrammed dispatch,
+      # slice 3, whole-project table-unification survey):
+      # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, an explicit table
+      # naming the same (context, word) -> method pairs the real
+      # `calls:` column carries, projected ahead of time into the
+      # committed `bootstrap_table.rb` — it matters only for words both
+      # migrated to the `calls:` shape and bootstrap-reachable
+      # (`attribute`, for one). This is the one place in this whole arc a
       # bootstrap fallback was worth building despite `RuleReference`'s
-      # own precedent against it: it duplicates NO logic, only a METHOD
-      # NAME — `attribute_impl`'s own real, hand-written body is called
+      # own precedent against it: it duplicates no logic, only a method
+      # name — `attribute_impl`'s own real, hand-written body is called
       # either way, bootstrap or not, so there is nothing here that can
       # drift the way a full behavioral duplicate could.
       #
-      # TWO FURTHER PIECES, both slice 5:
+      # ## `word_gate_dispatch` and the type-position fallback
+      #
+      # Two further pieces, both slice 5:
       #   - `word_gate_dispatch` is the same admission+dispatch logic
       #     `method_missing` below runs, factored out so a class with
-      #     its OWN class-level `method_missing` (`HecksagonBuilder`'s/
+      #     its own class-level `method_missing` (`HecksagonBuilder`'s/
       #     `WorldBuilder`'s genuinely open-ended verb vocabulary) can
       #     call it directly and fall back to its own open-verb handling
       #     only when this returns `NOT_ADMITTED` — a class-level `def`
       #     always wins over an included module's in Ruby's own method
-      #     resolution, so their OWN `method_missing` is the only one
+      #     resolution, so their own `method_missing` is the only one
       #     that ever runs for them, and this is what lets a real,
       #     closed-set word (`port`/`realm`/`latest`) still reach
       #     `GenericDispatch` despite that.
@@ -84,7 +90,7 @@ module Hecks
       #     "Type" builder `self.class::GRAMMAR_CONTEXT` could ever
       #     name. See that method's own comment.
       module WordGate
-        # A caller with its OWN class-level `method_missing`
+        # A caller with its own class-level `method_missing`
         # (`HecksagonBuilder`/`WorldBuilder` — see `word_gate_dispatch`'s
         # own header) checks for this to tell "not a word the grammar
         # admits at all" apart from every other outcome below (a real
@@ -92,7 +98,7 @@ module Hecks
         # caller can fall through to its own open-ended handling instead.
         NOT_ADMITTED = Object.new.freeze
 
-        # PRIVATE, matching Ruby's own convention for both (`Object`
+        # Private, matching Ruby's own convention for both (`Object`
         # defines them private too) — and load-bearing here, not just
         # style: `spec/syntax_conformance_spec.rb`'s "declares every
         # word X answers" check walks `public_instance_methods`, and a
@@ -129,23 +135,23 @@ module Hecks
           result
         end
 
-        # THE CORE ADMISSION+DISPATCH LOGIC, factored out of
+        # The core admission+dispatch logic, factored out of
         # `method_missing` — item #13's full metaprogrammed dispatch
         # (slice 5, whole-project table-unification survey) — so a
-        # class with its OWN class-level `method_missing`
+        # class with its own class-level `method_missing`
         # (`HecksagonBuilder`'s/`WorldBuilder`'s genuinely open-ended
         # verb vocabulary, `persisted_by "Heki"`/`posted_by "Carrier"`,
-        # can never BE a closed table) can still route a word THE
-        # GRAMMAR ADMITS through here first, falling back to its own
+        # can never be a closed table) can still route a word the
+        # grammar admits through here first, falling back to its own
         # open-verb handling only for what this doesn't recognize at
         # all — unblocking `Hecksagon#port`/`World#realm`/`World#latest`,
         # each a real, closed-set word that happened to sit on a class
         # whose own `method_missing` a class-level `def` always wins
         # over Ruby's own module-inclusion order.
         #
-        # NEVER RAISES "not admitted" — returns `NOT_ADMITTED` instead,
+        # Never raises "not admitted" — returns `NOT_ADMITTED` instead,
         # so the caller (this module's own `method_missing`, or one of
-        # the two above) decides what that means for it. DOES still
+        # the two above) decides what that means for it. Does still
         # raise the richer, table-driven refusals below once a word is
         # admitted-but-unimplemented, or admitted-somewhere-else-only —
         # those are real, useful refusals regardless of which
@@ -161,16 +167,16 @@ module Hecks
           keywords = rows[:keywords]
           admitted = keywords.select { |row| row[:context] == context && (row[:word] == word.to_s || row[:was] == word.to_s) }
 
-          # THE TYPE-POSITION FALLBACK — item #13's full metaprogrammed
+          # **The type-position fallback** — item #13's full metaprogrammed
           # dispatch (slice 5). `one_of`/`list_of`, called inside an
           # attribute's own type argument (`attribute :x,
           # one_of("a","b")`), run with `self` as whatever builder is
-          # CURRENTLY instance_eval'ing — there is no dedicated "Type"
+          # currently instance_eval'ing — there is no dedicated "Type"
           # builder of its own; every attribute()-taking builder answers
           # these identically, through the shared `AttributeCollector`
-          # mixin. `self.class::GRAMMAR_CONTEXT` can never actually BE
+          # mixin. `self.class::GRAMMAR_CONTEXT` can never actually be
           # "Type", so a word admitted only there would otherwise look
-          # inadmissible everywhere. Checked only once THIS context has
+          # inadmissible everywhere. Checked only once this context has
           # already come up empty, so a context with its own same-named
           # row (`ValueObject`'s own `one_of`, the block-wrapper form)
           # keeps using that instead, unaffected.
@@ -190,11 +196,11 @@ module Hecks
                   "'#{word}' is not a word #{context} admits — legal words here: #{legal.join(', ')}"
           end
 
-          # ITEM #13's FULL METAPROGRAMMED DISPATCH — the word IS
+          # Item #13's full metaprogrammed dispatch — the word is
           # admitted here, and this builder has no hand-written method
           # left for it; before falling through to the "not yet
           # implemented" refusal every word without one still gets,
-          # offer it to GenericDispatch — the SAFE, verified subset of
+          # offer it to GenericDispatch — the safe, verified subset of
           # words whose whole behavior is now executed off this same
           # table, not just checked against it.
           dispatched = GenericDispatch.try(self, context, word.to_s, args, kwargs, block, rows)
@@ -215,13 +221,13 @@ module Hecks
             super
         end
 
-        # A word admitted SOMEWHERE, just not in THIS context, still
+        # A word admitted somewhere, just not in this context, still
         # falls through to Ruby's own `NoMethodError` rather than this
         # module's own richer refusal — `method_missing` fires for
         # every typo in the whole codebase (this class's own genuinely
         # private helper methods included), not just DSL keyword calls;
-        # only raise the RICH, table-driven message when the word is at
-        # least SOMETHING the grammar knows about, anywhere, so an
+        # only raise the rich, table-driven message when the word is at
+        # least something the grammar knows about, anywhere, so an
         # unrelated Ruby-level typo inside a builder's own private code
         # keeps its own ordinary, unconfusing `NoMethodError`.
         def admitted_anywhere?(rows, word)

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

@@ -8,6 +8,7 @@ module Hecks
       # vocabulary of its own; `WorldBuilder#record_binding` reads `#to_h`
       # back out.
       class SettingsCollector
+        # Starts with no settings recorded.
         def initialize = @values = {}
 
         def method_missing(key, *args, &)
@@ -19,9 +20,9 @@ module Hecks
         def to_h = @values
       end
 
-      # THE AGGREGATE-QUALIFIED MIRROR (#143) — a `.world` file's own
+      # The aggregate-qualified mirror (#143) — a `.world` file's own
       # `Pizzas::Order.charged_by("Stripe") do ... end` visually mirrors the
-      # SAME bind line the sibling `.hecksagon` file already writes
+      # same bind line the sibling `.hecksagon` file already writes
       # (`HecksagonBuilder`'s own `BindingProxy`), but `IR::World#for_verb`/
       # `#for_binding` key purely by verb and adapter name — the aggregate
       # qualifier is never read back out, it exists only for that visual
@@ -30,12 +31,19 @@ module Hecks
       # not, has to land in the exact same `@settings` write path
       # (`WorldBuilder#record_binding`).
       class WorldConstProxy
+        # Mints the stand-in module a bare domain constant resolves to inside a `.world` block.
+        #
+        # @param builder [Bluebook::DSL::WorldBuilder] the builder every verb called through the
+        #   module's proxies records its settings on
+        # @return [Module] an anonymous module whose `const_missing` answers a `WorldConstProxy`,
+        #   whatever aggregate name follows `::`
         def self.namespace(builder)
           Module.new do
             define_singleton_method(:const_missing) { |_aggregate| WorldConstProxy.new(builder) }
           end
         end
 
+        # @param builder [Bluebook::DSL::WorldBuilder] the builder verb calls are recorded on
         def initialize(builder) = @builder = builder
 
         def method_missing(verb, *args, **kwargs, &block) = @builder.record_binding(verb, args, kwargs, block)
@@ -45,7 +53,7 @@ module Hecks
 
       # Parses a `.world` file's top-level DSL block into a `World` — a
       # domain's own `realm`/`latest` version markers plus its adapter bind
-      # SETTINGS, one entry per `verb("Adapter") do ... end` call (whether
+      # settings, one entry per `verb("Adapter") do ... end` call (whether
       # written bare or aggregate-qualified through `WorldConstProxy`'s
       # visual mirror of a sibling `.hecksagon` file's own bind).
       class WorldBuilder
@@ -53,23 +61,37 @@ module Hecks
 
         include WordGate
 
+        # @param domain [String] name of the domain whose world this is
         def initialize(domain)
           @domain   = domain
           @settings = {}
         end
 
-        # RENAMED FROM `realm`/`latest` — item #13's full metaprogrammed
-        # dispatch (slice 5). Neither bootstrap-reachable (checked
-        # directly). Reached through `WordGate#method_missing`'s new
+        # Names the realm this world belongs to, such as `"Examples"` or `"QA"`.
+        #
+        # `realm_impl`/`latest_impl` answer the `realm`/`latest` words
+        # through the table's `calls:` column — item #13's full
+        # metaprogrammed dispatch (slice 5). Neither bootstrap-reachable
+        # (checked directly). Reached through `WordGate`'s
         # `word_gate_dispatch`, called explicitly below since
         # `WorldBuilder`'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 value [String, Symbol] the realm's name; blankness is judged by the world
+        #   language at `build`, not here
+        # @return [String] the realm as stored
         def realm_impl(value)
           @realm = required(value, "realm")
         end
 
+        # Names the bluebook version this world treats as latest, which `ProjectRegister` compares
+        # with the bluebook's own declared `version`.
+        #
+        # @param value [String, Symbol, Numeric] the version marker; blankness is judged by the
+        #   world language at `build`, not here
+        # @return [String] the version as stored
         def latest_impl(value)
           @latest = required(value, "latest version")
         end
@@ -83,11 +105,20 @@ module Hecks
 
         def respond_to_missing?(_name, _include_private = false) = true
 
-        # EXTRACTED from the old `method_missing` body (#143) so
+        # Records one bind's settings under both its verb and its `verb:adapter` key.
+        #
+        # A method of its own, apart from `method_missing` (#143), so
         # `WorldConstProxy`'s own aggregate-qualified verb calls
         # (`Pizzas::Order.charged_by(...)`) write into the exact same
         # place the bare top-level spelling (`charged_by(...)`) already
         # does — one write path, two spellings.
+        #
+        # @param verb [Symbol, String] the bind verb, such as `:persisted_by`
+        # @param args [Array<Object>] the call's positional arguments; the first names the adapter
+        # @param kwargs [Hash{Symbol => Object}] settings given inline as keyword arguments
+        # @param block [Proc, nil] a settings block, evaluated against a `SettingsCollector`
+        # @return [Hash{Symbol => Object}] the settings just recorded: `:adapter` (a String),
+        #   then the keyword arguments, then the block's settings, later ones winning
         def record_binding(verb, args, kwargs, block)
           collector = SettingsCollector.new
           collector.instance_eval(&block) if block
@@ -96,18 +127,30 @@ module Hecks
           @settings["#{verb}:#{args.first.to_s.downcase}"] = value
         end
 
+        # Assembles the realm, version marker and bind settings, judged by the world language.
+        #
+        # @return [Bluebook::World] the world, returned once the language accepts it
+        # @raise [Bluebook::DSL::Malformed] if the world language refuses the declaration, such
+        #   as a blank `realm`
         def build
           MetaValidator.call_world(
             World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings)
           )
         end
 
+        # Evaluates a `Hecks.world` block against a fresh builder and returns the world it declared.
+        #
         # `ConstShim`'s resolver, the same bridge `HecksagonBuilder`/
         # `BluebookBuilder` already wrap their own `instance_eval` in
-        # (#143) — without it, `Pizzas::Order.charged_by(...)` raised
+        # (#143) — without it, `Pizzas::Order.charged_by(...)` raises
         # `NameError: uninitialized constant Pizzas` for every `.world`
         # file using the aggregate-qualified mirror form, since a bare
         # `Pizzas` has no real constant to resolve to.
+        #
+        # @param domain [String] name of the domain whose world this is
+        # @yield the world body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::World] the judged world
+        # @raise [Bluebook::DSL::Malformed] if the world language refuses the declaration
         def self.build(domain, &block)
           builder  = new(domain)
           resolver = ->(_domain) { WorldConstProxy.namespace(builder) }

data/lib/hecks/bluebook/entity.rb

@@ -3,10 +3,10 @@ require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    # An entity, as a RUBY CLASS — a piece of an aggregate that has an identity
+    # An entity, as a Ruby class — a piece of an aggregate that has an identity
     # of its own.
     #
-    # Crossing over closes the OWNER CHAIN. An entity declares commands, and
+    # Crossing over closes the owner chain. An entity declares commands, and
     # until now those commands had no owner that could state an identity: an
     # entity was an IR object, not a construct, so `Construct#hecks_fqn` refused
     # rather than answering "Deposit" and looking right. Four of banking's
@@ -14,15 +14,15 @@ module Hecks
     # `Banking::Account.Ledger.Deposit` — which is the id the judge already mints
     # for them.
     #
-    # NOT const_set, for the same reason a command is not: a name inside one
+    # Not const_set, for the same reason a command is not: a name inside one
     # aggregate can denote more than one kind of thing, so the constant tree
     # cannot index it.
     #
-    # It must stay STRUCTURALLY INTERCHANGEABLE with an aggregate — the runtime
+    # It must stay structurally interchangeable with an aggregate — the runtime
     # builds `Instance.new(aggregate: entity)` and `CommandRules` takes either as
     # `declaring` — so it answers `hecks_name`, `attributes`, `attribute`,
     # `identified_by` and `lifecycle` exactly as an aggregate does. And it must
-    # keep NOT answering `value_object`: `Value.for_attribute` sniffs for that
+    # keep not answering `value_object`: `Value.for_attribute` sniffs for that
     # method to tell a piece from a head.
     class Entity
       extend Construct
@@ -39,26 +39,26 @@ module Hecks
         # S17, ADR 0026 — "That is what `entity` is for, and `entity` is
         # declared by the language and used zero times in it" (the ADR's
         # own words). Dispatch nests inside Handler, so an entity's own
-        # NESTED entities are part of its wire shape now, the same way
+        # nested entities are part of its wire shape now, the same way
         # an aggregate's always were — the field the ADR names as
         # declared-but-unused until this slice.
         entities:      many(:entities),
-        # ADR 0028 — a piece's own `given`, the SAME shape
+        # ADR 0028 — a piece's own `given`, the same shape
         # `Aggregate#preconditions` already carries (its own `emits_ir`
         # row, identical). A precondition shared across this piece's own
         # commands, declared once — a command references it back by
-        # name; the resolved text still lands on EACH referencing
+        # name; the resolved text still lands on each referencing
         # command's own `givens` either way, so this field is read-only
         # documentation of what the piece itself declared, the same
         # relationship `Aggregate.preconditions` already has to its own
         # commands.
         preconditions: -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # A piece's OWN shape rule, checked against EVERY instance of
+        # A piece's own shape rule, checked against every instance of
         # this piece the aggregate holds (Admissibility#enforce_
-        # invariants' own recursive walk) — the SAME relationship
+        # invariants' own recursive walk) — the same relationship
         # `ValueObject#invariants` already has to its own instances,
         # one level up the construct tree. Not a separate enforcement
-        # boundary; still checked at the SAME two points (after every
+        # boundary; still checked at the same two points (after every
         # mutation, before save) the aggregate's own invariants always
         # were — see that method's own comment for why this does not
         # contradict "there is no separate entity invariant."
@@ -70,6 +70,24 @@ module Hecks
         attr_reader :description, :identified_by, :identity_paths, :identity_heads,
                     :attributes, :commands, :queries, :entities, :preconditions, :invariants, :lifecycle
 
+        # Mints a new piece class for one declared entity and absorbs its fields into it.
+        #
+        # @param name [String, Symbol] the entity's declared name
+        # @param description [String, nil] the entity's declared prose description
+        # @param identified_by [String, Symbol, Array<String, Symbol>, nil] the identity
+        #   path(s) this entity is addressed by
+        # @param attributes [Array<Bluebook::Attribute>] the entity's declared fields
+        # @param commands [Array<Class>] the command classes (`Bluebook::Command` subclasses)
+        #   declared on this entity
+        # @param queries [Array<Bluebook::Query>] the queries declared on this entity
+        # @param entities [Array<Class>] the entity classes (`Bluebook::Entity` subclasses)
+        #   nested directly under this entity
+        # @param preconditions [Array<Bluebook::Given>] this entity's own named `given`s
+        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every
+        #   instance of this entity
+        # @param lifecycle [Bluebook::Lifecycle, nil] the entity's declared state machine,
+        #   or `nil` if it declares none
+        # @return [Class] the minted piece class (a `Bluebook::Entity` subclass)
         def declare(name:, description: nil, identified_by: nil, attributes: [],
                     commands: [], queries: [], entities: [], preconditions: [], invariants: [], lifecycle: nil)
           piece = Class.new(self)
@@ -85,6 +103,17 @@ module Hecks
         # Assigns what the language declares, then hands off to the
         # behaviour's own `settle` — derived identity and the name
         # indexes, neither of which the declaration states.
+        #
+        # @param description [String, nil] see `declare`
+        # @param identified_by [String, Symbol, Array<String, Symbol>, nil] see `declare`
+        # @param attributes [Array<Bluebook::Attribute>] see `declare`
+        # @param commands [Array<Class>] see `declare`
+        # @param queries [Array<Bluebook::Query>] see `declare`
+        # @param entities [Array<Class>] see `declare`
+        # @param preconditions [Array<Bluebook::Given>] see `declare`
+        # @param invariants [Array<Bluebook::Invariant>] see `declare`
+        # @param lifecycle [Bluebook::Lifecycle, nil] see `declare`
+        # @return [Class] this piece's own class, self, once identity and indexes are derived
         def absorb(description:, identified_by:, attributes:, commands:, queries:, entities:, preconditions:, invariants:,
                    lifecycle:)
           @description    = description