hecks 2.7.0 → 2.9.0

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

@@ -2,126 +2,27 @@ require_relative "generic_dispatch"
 module Hecks
   module Bluebook
     module DSL
-      # 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
-      # per-construct parsing runs. Ruby never lexes source text — a
-      # `.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
-      # 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.
+      # Checks undefined DSL words against the self-hosted grammar table, dispatching admitted ones
+      # through `GenericDispatch` and refusing the rest with the table's own message.
       #
-      # ## What reaches this module
-      #
-      # `method_missing`/`respond_to_missing?` only — a word this
-      # builder class already answers with an ordinary `def` (or a
-      # method a shared mixin such as `AttributeCollector` defines) never
-      # reaches this module at all; Ruby's own method lookup finds it
-      # 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
-      # the Rust side, read off the identical table.
-      #
-      # ## 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
-      # check them against. For most words, this module steps aside
-      # entirely during bootstrap (`super`, Ruby's own ordinary
-      # `NoMethodError`) — the exact behavior every builder already had
-      # before this module existed, and (unlike `RuleReference`) there
-      # is deliberately no fallback covering the whole ~200-row table —
-      # that would defeat the entire point.
-      #
-      # 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
-      # either way, bootstrap or not, so there is nothing here that can
-      # drift the way a full behavioral duplicate could.
-      #
-      # ## `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/
-      #     `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
-      #     that ever runs for them, and this is what lets a real,
-      #     closed-set word (`port`/`realm`/`latest`) still reach
-      #     `GenericDispatch` despite that.
-      #   - the "Type"-position fallback inside `word_gate_dispatch`
-      #     itself, for `one_of`/`list_of` — called inside an
-      #     attribute's own type argument, with `self` as whatever
-      #     builder is currently `instance_eval`ing, never a dedicated
-      #     "Type" builder `self.class::GRAMMAR_CONTEXT` could ever
-      #     name. See that method's own comment.
+      # Each including class names its grammar row in `GRAMMAR_CONTEXT`. While the meta-domain
+      # boots there is no table, so only `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK` applies.
       module WordGate
-        # 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
-        # dispatch, or a raised refusal) — never raised itself, so a
-        # caller can fall through to its own open-ended handling instead.
+        # Returned by `word_gate_dispatch` for a word no grammar row admits, so a caller with
+        # its own `method_missing` can fall back to open-ended handling.
         NOT_ADMITTED = Object.new.freeze
 
-        # 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
-        # public `method_missing`/`respond_to_missing?` would show up
-        # there as two more "answered words" no row of the grammar ever
-        # declares, on every builder this module touches.
+        # Private like Object's own; public ones would appear as extra "answered words" in
+        # spec/syntax_conformance_spec.rb, which walks `public_instance_methods`.
 
         private
 
         def method_missing(word, *args, **kwargs, &block)
           if MetaValidator.bootstrapping?
             fallback = GenericDispatch::BOOTSTRAP_CALLS_FALLBACK
-            # Own context first, "Type" second — the same order the
-            # ordinary (non-bootstrapping) `word_gate_dispatch` path
-            # below checks them in, for the same reason: `list_of`/
-            # `one_of` used in an attribute's own type position never
-            # arrive with `self.class::GRAMMAR_CONTEXT == "Type"`.
+            # Own context first, then "Type", as in `word_gate_dispatch`.
             own_key  = [self.class::GRAMMAR_CONTEXT, word.to_s]
             type_key = ["Type", word.to_s]
-            # key? first, never `||` — a target method name is never
-            # actually stored as `false`, but the fallback lookup itself
-            # must not silently prefer "Type" over this class's own
-            # context on the strength of a falsy-looking value.
             found  = fallback.key?(own_key) || fallback.key?(type_key)
             target = fallback.key?(own_key) ? fallback[own_key] : fallback[type_key]
             return send(target, *args, **kwargs, &block) if found
@@ -135,31 +36,8 @@ module Hecks
           result
         end
 
-        # 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`
-        # (`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
-        # 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,
-        # so the caller (this module's own `method_missing`, or one of
-        # 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
-        # `method_missing` is asking.
-        # One ordered admission-then-dispatch pipeline (own context, then
-        # "Type" fallback, then admitted-elsewhere check, then dispatch) —
-        # see this method's own header comment above for the full,
-        # order-dependent account of why each check runs where it does.
+        # Admission then dispatch: own context, "Type" fallback, admitted-elsewhere check,
+        # `GenericDispatch`. Returns `NOT_ADMITTED` for an unknown word rather than raising.
         # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def word_gate_dispatch(word, args, kwargs, block)
           context = self.class::GRAMMAR_CONTEXT
@@ -167,19 +45,9 @@ 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
-          # 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"
-          # builder of its own; every attribute()-taking builder answers
-          # these identically, through the shared `AttributeCollector`
-          # 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
-          # 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.
+          # `one_of`/`list_of` in an attribute's type position run on whichever builder is
+          # evaluating, whose context is never "Type". Try "Type" only when its own context has
+          # no row, so a same-named row of its own (ValueObject's `one_of`) still wins.
           if admitted.empty?
             type_admitted = keywords.select { |row| row[:context] == "Type" && row[:word] == word.to_s }
             unless type_admitted.empty?
@@ -196,13 +64,6 @@ module Hecks
                   "'#{word}' is not a word #{context} admits — legal words here: #{legal.join(', ')}"
           end
 
-          # 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
-          # 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)
           return dispatched unless dispatched.equal?(GenericDispatch::NOT_HANDLED)
 
@@ -221,15 +82,8 @@ module Hecks
             super
         end
 
-        # 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
-        # unrelated Ruby-level typo inside a builder's own private code
-        # keeps its own ordinary, unconfusing `NoMethodError`.
+        # `method_missing` fires for every typo in a builder, so only words the grammar knows
+        # anywhere get the rich refusal; other typos keep Ruby's ordinary `NoMethodError`.
         def admitted_anywhere?(rows, word)
           rows.any? { |row| row[:word] == word.to_s || row[:was] == word.to_s }
         end

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

@@ -2,17 +2,13 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # A generic keyword-call sink for one bind's own settings block (e.g.
-      # `persisted_by "Heki" do dir :default end`) — every method call made
-      # on it inside the block is recorded verbatim by name, with no fixed
-      # vocabulary of its own; `WorldBuilder#record_binding` reads `#to_h`
-      # back out.
+      # Records every keyword call made inside a bind's settings block, by name, with
+      # no fixed vocabulary of its own.
       class SettingsCollector
-        # Starts with no settings recorded.
         def initialize = @values = {}
 
-        # A call with a block records the block's own settings as a nested Hash, so a bind can
-        # group settings (`preview do ... end`); a call without one records its argument.
+        # A call with a block records its own settings as a nested Hash; a bare call
+        # keeps a single argument as is, several as an array.
         def method_missing(key, *args, &block)
           @values[key.to_sym] =
             if block
@@ -29,30 +25,15 @@ module Hecks
         def to_h = @values
       end
 
-      # 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
-      # (`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
-      # mirroring. So unlike `BindingProxy`, nothing here needs to hold onto
-      # the resolved constant chain at all: every verb call, qualified or
-      # not, has to land in the exact same `@settings` write path
-      # (`WorldBuilder#record_binding`).
+      # Stands in for a bare aggregate constant inside a `.world` block, so a bind line
+      # can visually mirror its sibling `.hecksagon` spelling; the qualifier is never read back out.
       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)
@@ -60,76 +41,36 @@ module Hecks
         def respond_to_missing?(_name, _include_private = false) = true
       end
 
-      # 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
-      # written bare or aggregate-qualified through `WorldConstProxy`'s
-      # visual mirror of a sibling `.hecksagon` file's own bind).
+      # Parses a `.world` file's top-level DSL block into a `World` — a domain's own
+      # `realm`/`latest` markers plus its adapter bind settings.
       class WorldBuilder
         GRAMMAR_CONTEXT = "World".freeze
 
         include WordGate
 
-        # @param domain [String] name of the domain whose world this is
         def initialize(domain)
           @domain   = domain
           @settings = {}
         end
 
-        # 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
+        # Reached through `WordGate`'s `word_gate_dispatch`, called explicitly since this
+        # class's own `method_missing` would otherwise always win over the module's.
         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
+        # `ProjectRegister` compares this against the bluebook's own declared `version`.
         def latest_impl(value)
           @latest = required(value, "latest version")
         end
 
-        # Names the connection every chapter's database-taking persistence adapter uses
-        # unless that chapter's own world settings name one.
-        #
-        # Answers the `default_database` word through the table's `calls:` column, the
-        # same way `realm_impl` does. A chapter's own
-        # `persisted_by("Adapter") { database ... }` still wins for that adapter.
-        #
-        # @param value [String] the connection, such as a database URL; blankness is
-        #   judged by the world language at `build`, not here
-        # @return [String] the connection as stored
+        # A chapter's own `persisted_by("Adapter") { database ... }` still wins for that adapter.
         def default_database_impl(value)
           @default_database = required(value, "default database")
         end
 
-        # Names the persistence adapter every aggregate binds to unless its own chapter's
-        # hecksagon binds it.
-        #
-        # Answers the `default_adapter` word through the table's `calls:` column, the same
-        # way `realm_impl` does. Sits between an explicit bind and the framework's
-        # in-memory fallback; whether the adapter really is a persistence adapter is
-        # judged at boot, where adapters are known.
-        #
-        # @param value [String, Symbol] the adapter's declared name, such as `"PostgresEra"`;
-        #   blankness is judged by the world language at `build`, not here
-        # @return [String] the adapter name as stored
+        # Sits between an explicit bind and the framework's in-memory fallback; whether the
+        # adapter really is a persistence adapter is judged at boot, where adapters are known.
         def default_adapter_impl(value)
           @default_adapter = required(value, "default adapter")
         end
@@ -143,20 +84,8 @@ module Hecks
 
         def respond_to_missing?(_name, _include_private = false) = true
 
-        # 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
+        # A method of its own, apart from `method_missing`, so `WorldConstProxy`'s
+        # aggregate-qualified verb calls write into the same place the bare spelling does.
         def record_binding(verb, args, kwargs, block)
           collector = SettingsCollector.new
           collector.instance_eval(&block) if block
@@ -165,11 +94,6 @@ 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,
@@ -177,19 +101,8 @@ module Hecks
           )
         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(...)` 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
+        # Wraps `instance_eval` in `ConstShim`'s resolver: without it, an aggregate-qualified
+        # verb call raises `NameError`, since the bare constant has nothing to resolve to.
         def self.build(domain, &block)
           builder  = new(domain)
           resolver = ->(_domain) { WorldConstProxy.namespace(builder) }
@@ -200,7 +113,7 @@ module Hecks
         private
 
         def required(value, _label)
-          # moved to the language: Realm / Latest invariants, in world.bluebook
+          # Validation lives in the world language (world.bluebook), not here.
           value.to_s
         end
       end

data/lib/hecks/bluebook/entity.rb

@@ -3,28 +3,11 @@ require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    # 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
-    # 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
-    # commands were in that state. They can say what they are now —
-    # `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
-    # 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
-    # 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
-    # method to tell a piece from a head.
+    # An entity as a Ruby class: a piece of an aggregate that has an identity of its own.
+    # Not const_set, because a name inside one aggregate can denote more than one kind of thing.
     class Entity
+      # Stays interchangeable with an aggregate (`Instance.new(aggregate: entity)`, `CommandRules`
+      # `declaring`) but must not answer `value_object`, which `Value.for_attribute` sniffs for.
       extend Construct
       extend Hecks::IR
       extend Behaviour::Entity
@@ -36,32 +19,12 @@ module Hecks
         attributes:    many(:attributes),
         commands:      many(:commands),
         queries:       many(:queries),
-        # 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
-        # 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
-        # `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
-        # 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.
+        # Read-only record of the piece's own `given`; resolved text lands on each command's
+        # `givens`.
         preconditions: -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # 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
-        # `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
-        # 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."
+        # Checked against every instance of this piece, at the same points as an aggregate's
+        # invariants.
         invariants:    -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         lifecycle:     one(:lifecycle)
       )
@@ -73,20 +36,11 @@ module Hecks
         # 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
+        # @param commands [Array<Class>] the command classes declared on this entity
+        # @param entities [Array<Class>] the entity classes nested directly under this entity
+        # @param lifecycle [Bluebook::Lifecycle, nil] the declared state machine, or `nil`
         # @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)
@@ -100,20 +54,8 @@ module Hecks
           piece
         end
 
-        # 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
+        # Assigns the declared fields, then lets the behaviour's `settle` derive identity and
+        # indexes.
         def absorb(description:, identified_by:, attributes:, commands:, queries:, entities:, preconditions:, invariants:,
                    lifecycle:)
           @description    = description