hecks 1.4.0 → 1.5.1

data/lib/hecks/bluebook/project_loader.rb

@@ -14,14 +14,31 @@ module Hecks
 
       attr_reader :root, :discovery, :register
 
+      # Discovers and loads every domain under `root` in one call.
+      #
+      # @param root [String] the directory to search under
+      # @return [Bluebook::ProjectLoader] the loader, with every discovered domain
+      #   booted and registered
       def self.load(root) = new(root).load
 
+      # @param root [String] the directory to search under
+      # @param discovery [Bluebook::ProjectDiscovery] the discovery this loader walks
+      #   `root` with
+      # @param register [Bluebook::ProjectRegister] the register booted domains are
+      #   fed into
       def initialize(root, discovery: ProjectDiscovery.new(root), register: ProjectRegister.new)
         @root      = File.expand_path(root)
         @discovery = discovery
         @register  = register
       end
 
+      # Boots every domain `discovery` finds under `root` and registers its declarations.
+      #
+      # @return [Bluebook::ProjectLoader] self
+      # @raise [Bluebook::ProjectRegister::MissingRealm] see `ProjectRegister#register`
+      # @raise [Bluebook::ProjectRegister::LatestMismatch] see `ProjectRegister#register`
+      # @raise [Bluebook::ProjectRegister::DuplicateFqn] see `ProjectRegister#register`
+      # @raise [Runtime::WiringError] see `ProjectRegister#register`
       def load
         discovery.bluebook_directories.each do |directory|
           runtime = Runtime.boot(directory)
@@ -30,10 +47,33 @@ module Hecks
         self
       end
 
+      # Lists every registered entry.
+      #
+      # @return [Hash{String => Bluebook::ProjectRegister::Entry}] every registered
+      #   entry, keyed by its FQN
       def entries = register.entries
+
+      # Finds a registered entry by its fully-qualified verb.
+      #
+      # @param address [String, #to_s] the FQN to look up
+      # @return [Bluebook::ProjectRegister::Entry] the entry registered under `address`
+      # @raise [KeyError] if no entry is registered under `address`
       def fetch(address) = register.fetch(address)
+
+      # Says whether an entry is registered under an address.
+      #
+      # @param address [String, #to_s] the FQN to check
+      # @return [Boolean] whether an entry is registered under `address`
       def include?(address) = register.include?(address)
+
+      # Lists every registered command entry.
+      #
+      # @return [Array<Bluebook::ProjectRegister::Entry>] every registered command entry
       def commands = register.commands
+
+      # Lists every registered query entry.
+      #
+      # @return [Array<Bluebook::ProjectRegister::Entry>] every registered query entry
       def queries  = register.queries
     end
   end

data/lib/hecks/bluebook/project_register.rb

@@ -4,7 +4,14 @@ module Hecks
     # declarations become public FQNs, but never searches or boots folders.
     class ProjectRegister
       Entry = Struct.new(:fqn, :source_directory, :dispatcher, :declared_verb, :domain_version, keyword_init: true) do
+        # Says whether this entry addresses a command.
+        #
+        # @return [Boolean] whether this entry's `fqn` addresses a command
         def command? = fqn.command?
+
+        # Says whether this entry addresses a query.
+        #
+        # @return [Boolean] whether this entry's `fqn` addresses a query
         def query?   = fqn.query?
       end
 
@@ -14,16 +21,53 @@ module Hecks
 
       attr_reader :entries
 
+      # Starts an empty register, with no domains loaded yet.
       def initialize
         @entries = {}
         @tenant_directories = Hash.new { |hash, key| hash[key] = [] }
       end
 
+      # Finds a registered entry by its fully-qualified verb.
+      #
+      # @param address [String, #to_s] the FQN to look up, such as `"Pizzas.Pizza.Order"`
+      # @return [Bluebook::ProjectRegister::Entry] the entry registered under `address`
+      # @raise [KeyError] if no entry is registered under `address`
       def fetch(address) = entries.fetch(address.to_s)
+
+      # Says whether an entry is registered under an address.
+      #
+      # @param address [String, #to_s] the FQN to check
+      # @return [Boolean] whether an entry is registered under `address`
       def include?(address) = entries.key?(address.to_s)
+
+      # Lists every registered command entry.
+      #
+      # @return [Array<Bluebook::ProjectRegister::Entry>] every registered command entry
       def commands = entries.values.select(&:command?)
+
+      # Lists every registered query entry.
+      #
+      # @return [Array<Bluebook::ProjectRegister::Entry>] every registered query entry
       def queries  = entries.values.select(&:query?)
 
+      # Registers every aggregate command/query and read model query a booted chapter
+      # declares, under its versioned and (if current) unversioned FQNs.
+      #
+      # @param bluebooks [Array<Bluebook::Chapter>] the booted chapters to register
+      # @param registry [Runtime::Registry] the registry `bluebooks` booted into
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+      #   dispatcher entries dispatch through
+      # @param directory [String] the source directory `bluebooks` was discovered under
+      # @return [Bluebook::ProjectRegister] self
+      # @raise [Bluebook::ProjectRegister::MissingRealm] if a bluebook's world declares no
+      #   realm
+      # @raise [Bluebook::ProjectRegister::LatestMismatch] if a world's `latest` disagrees
+      #   with its bluebook's own version
+      # @raise [Bluebook::ProjectRegister::DuplicateFqn] if an FQN this call would register
+      #   is already registered
+      # @raise [Runtime::WiringError] if a second tenant registers the same on-disk
+      #   directory while any of its aggregates binds to an adapter that is not
+      #   `tenant_capable?`
       def register(bluebooks, registry, dispatcher, directory)
         bluebooks.each do |bluebook|
           refuse_unless_safe_for_second_tenant!(bluebook, registry, directory)

data/lib/hecks/bluebook/query.rb

@@ -6,6 +6,11 @@ module Hecks
   # throughout this chapter reach for. See lib/hecks/bluebook.rb's own
   # header for what `Bluebook` is as a whole.
   module Bluebook
+    # Renders a captured Ruby value to its self-describing wire spelling.
+    #
+    # @param value [Object] any value an `emits_ir` field carries, such as a Symbol,
+    #   String, Hash, Array, or literal
+    # @return [String] the value rendered through `Hecks::Literal.render`
     def self.render_value(value) = Literal.render(value)
 
     # A query — an ask, declared on an aggregate or on one of its entities.
@@ -40,6 +45,25 @@ module Hecks
 
       attr_reader :name, :description, :attributes
 
+      # @param name [String, Symbol] the query's declared name
+      # @param description [String, nil] the query's declared prose description
+      # @param attributes [Array<Bluebook::Attribute>] the query's declared result fields
+      # @param wheres [Array<QuerySpecification::Common::WhereClause>] the declared filter
+      #   conditions
+      # @param order_by [QuerySpecification::Common::OrderBy, nil] the declared sort field
+      #   and direction, or `nil` for no explicit ordering
+      # @param limit [QuerySpecification::Common::LimitSpec, nil] the declared row limit,
+      #   or `nil` for none
+      # @param offset [QuerySpecification::Common::OffsetSpec, nil] the declared row offset,
+      #   or `nil` for none
+      # @param cursor [QuerySpecification::Common::CursorSpec, nil] the declared pagination
+      #   cursor, or `nil` for none
+      # @param authorization [QuerySpecification::Common::AuthorizationSpec, nil] the declared
+      #   authorization policy, or `nil` for none
+      # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] how this query
+      #   orders `nil` values; defaults to `NullSemantics.default` when omitted
+      # @param inspection [QuerySpecification::Common::InspectionSpec, nil] the declared
+      #   inspection mode, or `nil` for none
       def initialize(name:, description: nil, attributes: [], wheres: [],
                      order_by: nil, limit: nil, offset: nil, cursor: nil,
                      authorization: nil, null_semantics: nil,
@@ -59,6 +83,9 @@ module Hecks
       # group_by, scope_to). Declared emission covers the settled part
       # and `super` hands it over; the tail stays dynamic, which is the
       # honest description of it.
+      #
+      # @return [Hash] the declared emission, merged with whatever `extra_options_to_h`
+      #   the specification layer currently carries
       def to_h = super.merge(extra_options_to_h)
     end
   end

data/lib/hecks/bluebook/read_model.rb

@@ -31,9 +31,25 @@ module Hecks
 
       # `reference_name:`/`reference_target:` are nil for a rootless read
       # model (no `reference_to` declared) — `&.` throughout, rather than
-      # the `.to_s`/`.to_sym` this used to require unconditionally, so
+      # calling `.to_s`/`.to_sym` unconditionally, so
       # `reference_target.nil?` stays a real, checkable fact for the
       # interpreter instead of silently becoming `""`.
+      #
+      # @param name [String, Symbol] the read model's declared name
+      # @param description [String, nil] the read model's declared prose description
+      # @param reference_name [Symbol, String, nil] the local reference attribute this
+      #   read model roots at, or `nil` for a rootless read model
+      # @param reference_target [String, Symbol, nil] the rooted aggregate's name, or
+      #   `nil` for a rootless read model
+      # @param aggregate_heads [Array<Hash{Symbol => Object}>] the included aggregates, each
+      #   a row with `:aggregate` (the aggregate's name), `:as` (the output field name) and
+      #   `:many` (whether this head is a many-side join)
+      # @param group_by [Array<Hash{field: Symbol}>] the declared group-by fields, one row
+      #   per field
+      # @param count [Boolean, nil] whether this read model reduces to a row count; `nil`
+      #   when undeclared
+      # @param median_field [Symbol, nil] the field this read model reduces to the median
+      #   of, or `nil` when undeclared
       def initialize(name:, description: nil, reference_name: nil, reference_target: nil, aggregate_heads: [],
                      group_by: [], count: nil, median_field: nil, **)
         super(joins: aggregate_heads, **)
@@ -94,6 +110,10 @@ module Hecks
       # `WholeBluebook`, ...) for a fact nothing about them changed —
       # the exact `extra_options_to_h` reads for `cursor`/`offset`/etc,
       # applied here for the same reason.
+      #
+      # @return [Hash] the declared emission, with `aggregate_heads`/`group_by` rows
+      #   stringified, `count`/`median_field` merged in only when declared, and
+      #   `extra_options_to_h`'s own dynamic tail merged last
       def to_h
         reductions = {}
         reductions[:count] = true if @count

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,6 +30,8 @@ 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
@@ -36,6 +39,11 @@ module Hecks
       # The Aggregate this points at, or nil when the target belongs to
       # 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,6 +56,8 @@ 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}>"
 
@@ -66,6 +76,9 @@ module Hecks
       # (if same-shaped) owning aggregates, and `declared_in` is a
       # cross-reference for `resolve`, not part of what this attribute
       # 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

@@ -22,11 +22,15 @@ module Hecks
     # 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 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,
@@ -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)
@@ -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")
@@ -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
@@ -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

@@ -42,6 +42,17 @@ module Hecks
       # 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?
@@ -59,6 +70,16 @@ module Hecks
       # 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.
+      #
+      # @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
@@ -75,6 +96,13 @@ module Hecks
       # 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
@@ -83,6 +111,12 @@ module Hecks
       # 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

@@ -19,7 +19,7 @@ module Hecks
     # 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
@@ -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

@@ -42,11 +42,11 @@ module Hecks
         # 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,10 +7,9 @@
 # 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