hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/reference.rb

@@ -2,15 +2,16 @@ module Hecks
   module Bluebook
     # An attribute that points at another aggregate's head.
     #
-    # This used to be the STRING `"Reference<Customer>"`, minted by
-    # `AggregateBuilder#reference_to` and `CommandBuilder#cross_reference` from
-    # a real constant that had just been handed in, and then parsed back apart
-    # by a regex in the command interpreter, by string equality in the read-model
-    # interpreter and the SQLite adapter, and by `delete_prefix` in the bluebook
-    # builder. Five readers of a spelling one writer invented.
+    # Holds the target directly, and answers `resolve` with the target's
+    # Aggregate, rather than being spelled as the string `"Reference<Customer>"`
+    # that `AggregateBuilder#reference_to` and `CommandBuilder#cross_reference`
+    # would otherwise mint from the real constant just handed in. That string
+    # would need five separate readers to parse back apart — a regex in the
+    # command interpreter, string equality in the read-model interpreter and
+    # the SQLite adapter, and `delete_prefix` in the bluebook builder — one
+    # writer inventing a spelling, five readers reparsing it.
     #
-    # It holds the TARGET instead, and answers `resolve` with the target's
-    # Aggregate. Resolution is LAZY and deliberately so: `reference_to
+    # Resolution is lazy and deliberately so: `reference_to
     # Customer` may name an aggregate declared lower in the file — banking's
     # Account points at Customer and survives only because Customer happens to
     # be written above — so the edge cannot be resolved at declaration time.
@@ -29,13 +30,20 @@ module Hecks
       # up to the chapter, stamped once every sibling has been read.
       attr_accessor :declared_in
 
+      # @param target_name [Module, String, Symbol] the aggregate constant this
+      #   reference points at, or its already-spelled name
       def initialize(target_name)
         @target_name = Naming.demodulise(target_name).to_s
       end
 
       # The Aggregate this points at, or nil when the target belongs to
-      # ANOTHER domain — a cross-domain target may legitimately not be loaded,
+      # another domain — a cross-domain target may legitimately not be loaded,
       # the same reading `across` policies get.
+      #
+      # @return [Bluebook::Aggregate, nil] the target aggregate, or `nil` when
+      #   `declared_in`'s own chapter does not declare one by this name
+      # @raise [DSL::Malformed] if `declared_in` is unset, so there is no
+      #   chapter to resolve the target against
       def resolve
         unless declared_in
           raise DSL::Malformed,
@@ -48,16 +56,18 @@ module Hecks
       end
 
       # The IR spelling, the one the export carries.
+      #
+      # @return [String] `"Reference<TargetName>"`
       def to_s = "Reference<#{@target_name}>"
       def inspect = "#<Reference #{@target_name}>"
 
-      # VALUE EQUALITY, not identity — without this, two references to
-      # the SAME target, parsed from two SEPARATE bluebook reads (era
+      # Value equality, not identity — without this, two references to
+      # the same target, parsed from two separate bluebook reads (era
       # N's own boot and a held era's own shadow reconstruction,
       # coverage_check.rb's own comparison), are different objects and
       # compare unequal by Ruby's default `==`. `EraGuard::ShapeDiff
       # #diff_type`'s `held_type != current_type` check then reads as
-      # true for EVERY reference_to attribute on EVERY mint, regardless
+      # true for every reference_to attribute on every mint, regardless
       # of whether the reference actually changed — a real refusal for
       # attributes nothing about. `declared_in` (which aggregate carries
       # this reference) is deliberately excluded: the same reference
@@ -65,7 +75,10 @@ module Hecks
       # from separately-parsed bluebooks with structurally different
       # (if same-shaped) owning aggregates, and `declared_in` is a
       # cross-reference for `resolve`, not part of what this attribute
-      # itself IS.
+      # itself is.
+      #
+      # @param other [Object] the value to compare against
+      # @return [Boolean] whether `other` is a `Reference` to the same target
       def ==(other) = other.is_a?(Reference) && target_name == other.target_name
       alias eql? ==
       def hash = [self.class, target_name].hash

data/lib/hecks/bluebook/smoke_test.rb

@@ -4,10 +4,10 @@ require "fileutils"
 
 module Hecks
   module Bluebook
-    # BOOTS A REAL BLUEBOOK AND ACTUALLY DISPATCHES AGAINST IT — the
+    # Boots a real bluebook and actually dispatches against it — the
     # sibling `bin/model_check` never had: that tool proves a bluebook
-    # is STRUCTURALLY sound (no dead states, no unreachable transitions)
-    # without ever running a single command; this proves it WORKS,
+    # is structurally sound (no dead states, no unreachable transitions)
+    # without ever running a single command; this proves it works,
     # catching exactly the class of bug static analysis structurally
     # cannot see. Built and proved inside `bin/interview`'s own `smoke`
     # command, where it first found two real bugs — a lifecycle field
@@ -15,20 +15,24 @@ module Hecks
     # missing `Command.ActsOn` — that reloaded clean, checked clean,
     # and only broke once something actually dispatched against them.
     #
-    # SYNTHESIZED ARGS, NEVER RANDOM (`Synthesizer`) — a String becomes
+    # Synthesized args, never random (`Synthesizer`) — a String becomes
     # a fixed marker, a closed set uses its own first admitted member, a
     # reference reuses whatever this same run already minted for that
-    # target. ONE call per declared command, ONE call per declared
+    # target. One call per declared command, one call per declared
     # report, per created root; every failure is collected and reported
     # together rather than stopping at the first.
     #
-    # WHAT THIS CANNOT CATCH: a call that dispatches cleanly but answers
-    # WRONG — the read-model join bug this exact tool's own first user
-    # hit is the textbook case, a query that silently returned an empty
-    # array rather than raising. Smoke-testing proves nothing crashes;
-    # it does not prove the answer is the right one.
+    # ## What this cannot catch
     #
-    # A FAILURE HERE IS NOT NECESSARILY A DOMAIN BUG, either — it may
+    # A call that dispatches cleanly but answers wrong — the read-model join
+    # bug this exact tool's own first user hit is the textbook case, a query
+    # that silently returned an empty array rather than raising.
+    # Smoke-testing proves nothing crashes; it does not prove the answer is
+    # the right one.
+    #
+    # ## False positives from a naive synthesizer
+    #
+    # A failure here is not necessarily a domain bug, either — it may
     # just be `Synthesizer`'s own naive values (0, an empty list,
     # "smoke-test") not satisfying a real invariant this simple
     # generator was never built to reason about (a positive amount, a
@@ -54,11 +58,11 @@ module Hecks
       # per-domain realm resolution requires and a plain boot never
       # did. Reports are reachable the identical way regardless of
       # boot path — `dispatcher.query("Domain.report_name", **args)`
-      # is the SAME `Dispatcher#query` either boot hands back; Router
-      # was never actually required for this, only its OWN namespace
-      # SUGAR (`Domain.report_name(...)` as a bare method call) was.
+      # is the same `Dispatcher#query` either boot hands back; Router
+      # was never actually required for this, only its own namespace
+      # sugar (`Domain.report_name(...)` as a bare method call) was.
       #
-      # NEVER BOOTS `dir`'S OWN REAL BINDINGS — measured, not a
+      # Never boots `dir`'s own real bindings — measured, not a
       # precaution taken on spec: pointed at `examples/pizzas` (a real,
       # persistent store carrying real accumulated records), a
       # synthesized `CreatePizza` collided with an actual pre-existing
@@ -73,7 +77,7 @@ module Hecks
       # `install_facade: false` — this only ever dispatches by FQN string
       # (below), so it never needs the `Widget::Item.Add(...)` Ruby
       # sugar `Hecks.boot` installs by default. Skipping it matters
-      # here specifically: that sugar lands as a BARE global constant on
+      # here specifically: that sugar lands as a bare global constant on
       # `Object` per domain and per aggregate name, with no scoping and
       # no cleanup — and this tool boots throwaway domains under
       # whatever generic names the caller's `.bluebook` happens to use
@@ -82,6 +86,11 @@ module Hecks
       # measured, not hypothetical: it once left a stale `Widget` constant
       # that corrupted an unrelated spec's own unrelated use of the same
       # bare name.
+      #
+      # @param dir [String] path to a bootable hecks app directory — a saved
+      #   domain, or a throwaway one rendered into a temp dir for this purpose
+      # @return [Array<Failure>] every dispatch or query failure collected,
+      #   empty when `dir` declares no bluebook or nothing failed
       def call(dir)
         Dir.mktmpdir("hecks-smoke-") do |scratch|
           isolate!(dir, scratch)
@@ -93,9 +102,9 @@ module Hecks
         end
       end
 
-      # ONLY THE `.bluebook`, NEVER `.world` EITHER — a real world's own
+      # Only the `.bluebook`, never `.world` either — a real world's own
       # settings (`persisted_by("Heki") { dir "..." }`) are keyed to the
-      # REAL adapter it names, not to Memory; copied verbatim, they
+      # real adapter it names, not to Memory; copied verbatim, they
       # apply to the wrong binding and refuse with a `WiringError`
       # ("Memory does not declare :dir") — measured, not assumed, the
       # first time this ran against Banking. A plain `Hecks.boot`
@@ -105,6 +114,11 @@ module Hecks
       # excluded — those are earlier, superseded versions of the same
       # domain; smoke-testing the current declaration is the point, not
       # its whole history.
+      #
+      # @param dir [String] path to the source hecks app directory to isolate
+      # @param scratch [String] path to the throwaway directory to copy the
+      #   `.bluebook` files into
+      # @return [void]
       def isolate!(dir, scratch)
         source = Adapters::Folder.new.bluebook_directory(dir)
         target = File.join(scratch, "bluebook")
@@ -112,8 +126,8 @@ module Hecks
         Dir.glob(File.join(source, "*.bluebook")).each { |file| FileUtils.cp(file, target) }
       end
 
-      # AGGREGATES WALKED IN DECLARATION ORDER, on purpose — so whatever
-      # a LATER aggregate's own shape needs from an EARLIER one (a
+      # Aggregates walked in declaration order, on purpose — so whatever
+      # a later aggregate's own shape needs from an earlier one (a
       # `TripItem` needing a real `PackingItem`, say) already exists by
       # the time that aggregate's own turn comes, the same reason
       # `Synthesizer#args_for`'s `created` map is threaded through in
@@ -123,6 +137,14 @@ module Hecks
       # documents; splitting would turn that ordering into an implicit contract on
       # parameter/return passing instead of one visible sequence.
       # rubocop:disable-next Metrics/AbcSize
+      #
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the
+      #   booted dispatcher to dispatch synthesized commands and queries through
+      # @param domain [String] the domain name to smoke-test, a key of
+      #   `dispatcher.registry.bluebooks`
+      # @return [Array<Failure>] every dispatch or query failure collected, in
+      #   declaration order; empty when `domain` names no loaded chapter or
+      #   nothing failed
       def smoke_domain(dispatcher, domain)
         chapter = dispatcher.registry.bluebook(domain)
         return [] unless chapter
@@ -136,7 +158,7 @@ module Hecks
           creating.each do |command|
             args = Synthesizer.args_for(chapter, aggregate, command, created)
             begin
-              result = dispatcher.dispatch("#{domain}::#{aggregate.name}.#{command.hecks_name}", **args)
+              result = dispatcher.dispatch_flat("#{domain}::#{aggregate.name}.#{command.hecks_name}", args)
               created[aggregate.name] = result.instance.id
             rescue StandardError => e
               failures << Failure.new(domain: domain, aggregate: aggregate.name, command: command.hecks_name,
@@ -146,7 +168,7 @@ module Hecks
 
             noncreating.each do |nc_command|
               nc_args = Synthesizer.args_for(chapter, aggregate, nc_command, created).merge(id: created[aggregate.name])
-              dispatcher.dispatch("#{domain}::#{aggregate.name}.#{nc_command.hecks_name}", **nc_args)
+              dispatcher.dispatch_flat("#{domain}::#{aggregate.name}.#{nc_command.hecks_name}", nc_args)
             rescue StandardError => e
               failures << Failure.new(domain: domain, aggregate: aggregate.name, command: nc_command.hecks_name,
                                       error: "#{e.class}: #{e.message}")
@@ -156,7 +178,8 @@ module Hecks
 
         chapter.read_models.each do |model|
           root_id = created[model.reference_target]
-          next unless root_id # nothing was created for this root — nothing to smoke-test yet, not a failure
+          # Nothing was created for this root — nothing to smoke-test yet, not a failure.
+          next unless root_id
 
           dispatcher.query("#{domain}.#{model.query_name}", model.reference_name => root_id)
         rescue StandardError => e

data/lib/hecks/bluebook/synthesizer.rb

@@ -1,12 +1,12 @@
 module Hecks
   module Bluebook
-    # ONE SYNTHESIZED ARGUMENT PER DECLARED ATTRIBUTE — never a random
+    # **One synthesized argument per declared attribute** — never a random
     # guess. Reads only real `IR` (`Aggregate`, `Command`,
-    # `Attribute`, `ValueObject`), so it works against ANY
+    # `Attribute`, `ValueObject`), so it works against any
     # loaded bluebook, not one particular domain: a String becomes a
-    # fixed marker; an Integer becomes 0; a closed set uses ITS OWN
+    # fixed marker; an Integer becomes 0; a closed set uses its own
     # first admitted member (never a value a real `one_of` would
-    # legitimately refuse); a reference uses whatever id the CALLER
+    # legitimately refuse); a reference uses whatever id the caller
     # already knows for that target (`created`), so a command whose
     # own shape depends on an earlier-created record — a `TripItem`
     # needing a real `PackingItem`, say — gets something real to work
@@ -16,8 +16,8 @@ module Hecks
     # got built and proved — the logic never actually knew anything
     # about the Interview domain or any one app; it only ever read IR.
     module Synthesizer
-      # THE ONLY TYPE NAMES THAT ARE EVER TRULY SCALAR — anything else
-      # a value object's own field names is ANOTHER value object,
+      # The only type names that are ever truly scalar — anything else
+      # a value object's own field names is another value object,
       # nested (`Pizza.price_cents: Price`, itself wrapping `cents:
       # Integer` — a real, ordinary shape, not an edge case). Missing
       # this the first time round meant a nested field silently
@@ -26,7 +26,7 @@ module Hecks
       # only by testing against Pizzas instead of re-testing against
       # the one simpler domain this was first built for, where every
       # value object happened to be single-field and primitive-typed.
-      # THE SAME LIST `Attribute::PRIMITIVES` holds, referenced rather
+      # The same list `Attribute::PRIMITIVES` holds, referenced rather
       # than repeated. It was a second, byte-identical copy — and only
       # the Attribute one is held to `vocabulary.bluebook` by
       # spec/vocabulary_conformance_spec, so this copy could drift from
@@ -38,10 +38,21 @@ module Hecks
       # `chapter`/`aggregate` are the real `Bluebook`/`Aggregate`
       # the command belongs to — needed to resolve a value object type
       # name back to its own declared shape. `created` maps an
-      # aggregate NAME to a real id already minted for it earlier in
+      # aggregate name to a real id already minted for it earlier in
       # the same run; a reference whose target isn't in there yet gets
       # a placeholder instead of failing outright, since the caller may
       # not care about that particular argument's real value.
+      #
+      # @param chapter [Bluebook::Chapter] the chapter the command's aggregate
+      #   belongs to, needed to resolve a value object type name back to its
+      #   own declared shape
+      # @param aggregate [Bluebook::Aggregate] the aggregate `command` belongs to
+      # @param command [Class] the command class (a `Bluebook::Command`
+      #   subclass) to synthesize arguments for
+      # @param created [Hash{String => Object}] aggregate name mapped to a real
+      #   id already minted for it earlier in this same run
+      # @return [Hash{Symbol => Object}] one synthesized value per declared
+      #   attribute, keyed by attribute name
       def args_for(chapter, aggregate, command, created = {})
         command.attributes.to_h do |attribute|
           if attribute.reference?
@@ -52,13 +63,23 @@ module Hecks
         end
       end
 
-      # A value object's OWN synthesized value — its first admitted
+      # A value object's own synthesized value — its first admitted
       # member if it's a closed set (the one value guaranteed not to be
       # refused), otherwise one synthesized scalar per declared field.
       # Falls back to searching every aggregate in the chapter, the
       # same tolerance `bin/interview shape`'s own lookup already
       # needed: a value object referenced by name doesn't have to be
-      # declared on the SAME aggregate using it.
+      # declared on the same aggregate using it.
+      #
+      # @param chapter [Bluebook::Chapter] the chapter to search when
+      #   `type_name` is not declared on `aggregate` itself
+      # @param aggregate [Bluebook::Aggregate] the aggregate `type_name` is
+      #   looked up on first
+      # @param type_name [String] the value object's declared type name
+      # @return [String, Hash{Symbol => Object}] the string `"smoke-test"` when
+      #   no such value object is declared; otherwise a Hash of one value per
+      #   field — the closed set's own first admitted member's fields, or one
+      #   freshly synthesized scalar per declared field
       def value_for(chapter, aggregate, type_name)
         value_object = aggregate.value_object(type_name) ||
                        chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
@@ -72,17 +93,30 @@ module Hecks
 
       # A single field's own synthesized value — a plain scalar if its
       # type is one of the true primitives, otherwise that type names
-      # ANOTHER value object, resolved the identical way `value_for`
+      # another value object, resolved the identical way `value_for`
       # resolves any other one (its own closed set or its own nested
       # fields, however deep that nesting actually goes).
+      #
+      # @param chapter [Bluebook::Chapter] see `value_for`
+      # @param aggregate [Bluebook::Aggregate] see `value_for`
+      # @param type_name [String] the field's declared type name
+      # @return [Integer, Float, true, false, String, Hash{Symbol => Object}] a
+      #   bare scalar when `type_name` is a true primitive (see `scalar_for`),
+      #   otherwise `value_for`'s own result for the nested value object it names
       def field_value_for(chapter, aggregate, type_name)
         PRIMITIVES.include?(type_name.to_s) ? scalar_for(type_name) : value_for(chapter, aggregate, type_name)
       end
 
       # A bare primitive's own synthesized value. Never used for a
-      # closed set's OWN field (that's `value_for`'s job, reading the
+      # closed set's own field (that's `value_for`'s job, reading the
       # set's real first member) — only for a plain scalar field with
       # no declared vocabulary to respect.
+      #
+      # @param primitive [String, Symbol] the primitive type name, such as
+      #   `"Integer"` or `"String"`
+      # @return [Integer, Float, false, String] `0` for `"Integer"`, `0.0` for
+      #   `"Float"`, `false` for `"TrueClass"`/`"FalseClass"`, or the string
+      #   `"smoke-test"` for anything else
       def scalar_for(primitive)
         case primitive.to_s
         when "Integer" then 0

data/lib/hecks/bluebook/translation.rb

@@ -5,7 +5,7 @@ module Hecks
     # Paths are dotted ("price.cents") for a VO member, bare otherwise.
     TranslationMove = Struct.new(:from, :to)
 
-    # One field whose VALUE, not just its name or position, changed —
+    # One field whose value, not just its name or position, changed —
     # an old value has nothing in common with a new one, so the only
     # honest way to bridge it is a declared, exhaustive lookup table.
     # Paths follow `TranslationMove`'s convention (dotted reaches a VO
@@ -16,10 +16,10 @@ module Hecks
     # rubocop:disable-next Lint/StructNewOverride
     TranslationConvert = Struct.new(:from, :to, :values)
 
-    # A value object's or entity's own TYPE NAME changed with its member
+    # A value object's or entity's own type name changed with its member
     # structure unchanged — the one drift `rename`/`move` cannot express,
     # because the attribute kept its name and only the type it points at
-    # was renamed. Mirrors `was:` one level deeper.
+    # changed name. Mirrors `was:` one level deeper.
     TranslationRetype = Struct.new(:from, :to)
 
     # A computed transform — rescale, reformat, split, merge — whose only
@@ -29,7 +29,7 @@ module Hecks
     # every other adapter.
     TranslationCompute = Struct.new(:from, :to, :sql)
 
-    # The aggregate's own IDENTITY changed what it's computed from — not
+    # The aggregate's own identity changed what it's computed from — not
     # a field crossing a boundary (that's `move`), a value objects's type
     # name (`retype`), or a value transform (`compute`): the record's own
     # key. No `from:`/`to:` path, unlike every other rule here, because
@@ -41,7 +41,7 @@ module Hecks
     TranslationRekey = Struct.new(:sql)
 
     # A newly added, required attribute with no source in old data at
-    # all — not a rename, move, or convert, all of which need a FROM
+    # all — not a rename, move, or convert, all of which need a from
     # path in the old shape. `default` is the value an existing record
     # reads until the next command against it writes a real one; unlike
     # `compute`, this is adapter-agnostic — applied in-process by
@@ -57,6 +57,23 @@ module Hecks
     class TranslationAggregate
       attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :computes, :rekeys, :backfills
 
+      # @param name [String, Symbol] the aggregate's name in the destination era
+      # @param was [String, Symbol, nil] the aggregate's name in the origin era, or `nil`
+      #   if it was not renamed
+      # @param renames [Hash{Symbol => Symbol}] each renamed field, old name to new name
+      # @param moves [Array<Bluebook::TranslationMove>] fields crossing a value-object
+      #   boundary
+      # @param converts [Array<Bluebook::TranslationConvert>] fields whose value is
+      #   remapped through a declared lookup table
+      # @param drops [Array<Symbol>] fields deliberately not carried forward
+      # @param retypes [Array<Bluebook::TranslationRetype>] value object or entity type
+      #   renames with their member structure unchanged
+      # @param computes [Array<Bluebook::TranslationCompute>] fields computed by a SQL
+      #   expression evaluated only inside the compiled Postgres head
+      # @param rekeys [Array<Bluebook::TranslationRekey>] SQL expressions that recompute
+      #   the aggregate's own identity
+      # @param backfills [Array<Bluebook::TranslationBackfill>] newly added required
+      #   fields with no source in old data
       def initialize(name:, was: nil, renames: {}, moves: [], converts: [], drops: [], retypes: [],
                      computes: [], rekeys: [], backfills: [])
         @name      = name.to_s
@@ -81,6 +98,13 @@ module Hecks
     class Translation
       attr_reader :domain, :from, :to, :aggregates, :retired
 
+      # @param domain [String, Symbol] the domain this translation carries forward
+      # @param from [String, Symbol] the origin era
+      # @param to [String, Symbol] the destination era
+      # @param aggregates [Array<Bluebook::TranslationAggregate>] each aggregate's own
+      #   translation rules
+      # @param retired [Array<String>] the names of aggregates gone outright in the
+      #   destination era, rather than renamed
       def initialize(domain:, from:, to:, aggregates: [], retired: [])
         @domain     = domain.to_s
         @from       = from
@@ -89,6 +113,11 @@ module Hecks
         @retired    = retired
       end
 
+      # Finds one aggregate's own translation rules by its destination-era name.
+      #
+      # @param name [String, Symbol] the aggregate's name in the destination era
+      # @return [Bluebook::TranslationAggregate, nil] the aggregate's translation, or
+      #   `nil` if `name` carries no translation rules
       def for_aggregate(name) = @aggregates.find { |aggregate| aggregate.name == name.to_s }
     end
   end

data/lib/hecks/bluebook/value_object.rb

@@ -5,7 +5,7 @@ module Hecks
   module Bluebook
     Invariant = Struct.new(:description, :canonical, :predicate, :ast, keyword_init: true)
 
-    # A value object — a DECLARATION HOLDER, never instantiated.
+    # A value object — a declaration holder, never instantiated.
     #
     # `ValueObjectBuilder` returns an anonymous subclass whose singleton
     # carries the declaration : attributes, invariants, members. Nothing ever
@@ -16,11 +16,11 @@ module Hecks
     #
     # `to_h` does not move. It is a byte-for-byte contract pinned by the
     # golden fixtures, so it keeps spelling the short declared name, which
-    # is what `hecks_name` carries. DECLARATIONS IN THE GRAPH, STRINGS IN THE
-    # EXPORT.
+    # is what `hecks_name` carries. Declarations in the graph, strings in the
+    # export.
     class ValueObject
       extend Construct
-      # EXTENDED, not included — this construct is a class, so its
+      # Extended, not included — this construct is a class, so its
       # emission is a class method. See Hecks::IR's own note on
       # the two shapes.
       extend Hecks::IR
@@ -29,7 +29,7 @@ module Hecks
       emits_ir(
         name:       :hecks_name,
         attributes: many(:attributes),
-        # `ast:` — a JSON-serializable rendering of the SAME predicate
+        # `ast:` — a JSON-serializable rendering of the same predicate
         # `canonical` already spells as text, alongside it rather than
         # replacing it (`canonical` stays the human-facing/doctest-facing
         # form; parsing it back would just re-derive what `ast` already
@@ -39,14 +39,14 @@ module Hecks
         # has no kernel crate to parse `canonical` with.
         invariants: -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         closed_set: :closed_set?,
-        # THE FIELD NAME IS STRINGIFIED, NEVER THE VALUE. A `member` row can
+        # The field name is stringified, never the value. A `member` row can
         # hold any of the scalar types an attribute declares — `Integer 84`
         # (`StatementFrequency#retention_months`, statements.bluebook), not
-        # only `String` — and `value.to_s` used to erase that on the way
-        # out, so `84` and `"84"` (a member some other row might
-        # legitimately spell as text) became indistinguishable once they
-        # reached `to_h`. The declared name still moves (`field.to_s`) —
-        # that half was never a Ruby object with a type to lose.
+        # only `String` — and stringifying it on the way out would erase
+        # that: `84` and `"84"` (a member some other row might legitimately
+        # spell as text) would become indistinguishable once they reached
+        # `to_h`. The declared name still moves (`field.to_s`) — that half
+        # was never a Ruby object with a type to lose.
         members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value] } } }
       )
 
@@ -55,6 +55,17 @@ module Hecks
 
         # One declared shape — a subclass rather than an instance, so the thing
         # the bluebook declares and the thing Ruby holds are one object.
+        #
+        # @param name [String, Symbol] the value object's declared type name
+        # @param attributes [Array<Bluebook::Attribute>] the value object's declared
+        #   fields
+        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every
+        #   instance of this value object
+        # @param members [Array<Hash{Symbol => Object}>] the declared `one_of` members, one
+        #   row of field values per member
+        # @param closed_set [Boolean] whether a `one_of` was declared, even with no
+        #   members; defaults to whether `members` is non-empty
+        # @return [Class] the minted shape class (a `Bluebook::ValueObject` subclass)
         def declare(name:, attributes: [], invariants: [], members: [], closed_set: !members.empty?)
           shape = Class.new(self)
           shape.hecks_name = name.to_s
@@ -63,6 +74,13 @@ module Hecks
           shape
         end
 
+        # Assigns what the language declares onto this shape class.
+        #
+        # @param attributes [Array<Bluebook::Attribute>] see `declare`
+        # @param invariants [Array<Bluebook::Invariant>] see `declare`
+        # @param members [Array<Hash{Symbol => Object}>] see `declare`
+        # @param closed_set [Boolean] see `declare`
+        # @return [void]
         def absorb(attributes:, invariants:, members:, closed_set:)
           @attributes = attributes
           @invariants = invariants

data/lib/hecks/bluebook.rb

@@ -7,13 +7,12 @@
 # DSL (dsl/), and the meta-validator that judges a chapter against the
 # language's own grammar (meta_validator.rb + meta_validator/).
 #
-# The require order below preserves the boot order the flat list in
-# lib/hecks.rb used to spell: expression and IR first (pure
-# declarations), assembly's collaborators before its face, the DSL before
-# the meta-validator that its builders call at build time.
+# The require order below matters: expression and IR load first (pure
+# declarations), assembly's collaborators load before its face, and the DSL
+# loads before the meta-validator that its builders call at build time.
 
 module Hecks
-  # Declared as a CLASS, not a module — `Hecks::Bluebook` IS a
+  # Declared as a class, not a module — `Hecks::Bluebook` is a
   # chapter (bluebook/chapter.rb carries its body). Everything a chapter
   # declares nests under it, as do the ways to build one (`DSL`) and to
   # judge one (`MetaValidator`). Reopening this anywhere must say `class`.
@@ -29,7 +28,7 @@ require_relative "literal"
 require_relative "query_specification"
 
 require_relative "bluebook/expression"
-# THE MODEL ITSELF — the chapter class's own body first, then everything
+# **The model itself** — the chapter class's own body first, then everything
 # a chapter declares. Order matters only for reading: each is a bag of
 # declarations with no load-time cross-references.
 require_relative "bluebook/chapter"