hecks 1.4.0 → 1.5.0

data/lib/hecks/behaviors/expectations.rb

@@ -7,6 +7,8 @@ require_relative "../ports/persistence/binding_policy"
 
 # Hecks::Behaviors::Expectations
 #
+# ## What it does
+#
 # One test case, start to finish: take the suite's own runtime (booted
 # once for exactly what its `loads` names, reset to nothing between
 # tests — `runtime_for`), replay `setup` dispatches, dispatch (or query)
@@ -14,6 +16,8 @@ require_relative "../ports/persistence/binding_policy"
 # runner.rb the same way the file-count/sweep concern is split from a
 # single test's own execution.
 #
+# ## Deviations from a prior port
+#
 # Two deliberate deviations from a prior port of this same idea (read
 # before writing this, not reinvented):
 #
@@ -46,6 +50,15 @@ module Hecks
       REFUSAL_CLASSES = Hecks::Runtime::DOMAIN_REFUSALS
       SPECIAL_KEYS = %i[ok refused emits count].freeze
 
+      # Runs one test case: replays its `setup` dispatches, dispatches (or queries)
+      # the command under test, and checks its `expect`.
+      #
+      # @param test [Behaviors::TestCase] the test case to run
+      # @param suite [Behaviors::BehaviorsSuite] the suite `test` belongs to
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher, nil] an
+      #   already-booted runtime to reuse and reset; nil boots (or reuses the cached
+      #   boot of) `suite.loads` via `runtime_for`
+      # @return [Result] the test's pass, fail, or error outcome
       def run_one(test, suite, runtime: nil)
         runtime ||= runtime_for(suite)
         runtime.registry.reset_runtime_state!
@@ -85,6 +98,14 @@ module Hecks
       RUNTIMES_LOCK = Mutex.new
       private_constant :RUNTIMES, :RUNTIMES_LOCK
 
+      # Boots (or reuses the cached boot of) the runtime a suite's `loads` names.
+      #
+      # @param suite [Behaviors::BehaviorsSuite] the suite whose `loads` files boot
+      #   the runtime
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the cached or
+      #   freshly booted, Memory-only-guarded runtime
+      # @raise [Malformed] if any aggregate the suite boots is not bound to the
+      #   default (Memory) adapter
       def runtime_for(suite)
         files = Array(suite.loads).map { |path| File.expand_path(path) }
         key   = files.map { |file| [file, File.exist?(file) ? File.mtime(file).to_f : nil] }
@@ -104,12 +125,25 @@ module Hecks
       # of guard `BindingPolicy` already applies to a missing bind — the
       # project's identity is refusing bad wiring up front, not
       # discovering it mid-suite.
+      #
+      # @param files [Array<String>] absolute paths to the bluebook/hecksagon/world
+      #   files to boot
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted,
+      #   Memory-only-guarded runtime
+      # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
       def boot_and_guard(files)
         runtime = Hecks::Runtime::Loader.boot_files(files, install_facade: false)
         guard_memory_only!(runtime)
         runtime
       end
 
+      # Refuses a runtime where any aggregate is bound to anything other than the
+      # default (Memory) adapter, so tests can never leak state or touch a real store.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+      #   runtime to check
+      # @return [void]
+      # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
       def guard_memory_only!(runtime)
         runtime.registry.bluebooks.each_value do |bluebook|
           bluebook.aggregates.each do |aggregate|
@@ -127,6 +161,15 @@ module Hecks
         end
       end
 
+      # Qualifies and dispatches (or queries) the command under test, catching a
+      # domain refusal as the test's own outcome rather than an error.
+      #
+      # @param test [Behaviors::TestCase] the test case to run
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted,
+      #   searched to qualify a bare command/query name
+      # @return [Result] the test's pass, fail, or error outcome
       def run_tested(test, runtime, bluebooks)
         verb = qualify(test.tests_command, test.on_aggregate, bluebooks, kind: test.kind)
 
@@ -139,6 +182,13 @@ module Hecks
         check_refusal(test, e)
       end
 
+      # Dispatches the command under test and checks its `expect`.
+      #
+      # @param test [Behaviors::TestCase] the test case to run
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the command's dotted FQN
+      # @return [Result] the test's pass or fail outcome
       def run_command(test, runtime, verb)
         before = runtime.registry.event_log.length
         result = dispatch_command(runtime, verb, test.input)
@@ -170,6 +220,15 @@ module Hecks
       # `emits:` saw MoveCountBumped in the same test). The repository
       # holds the settled record; read it back by the id the dispatch
       # itself answered with.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the dispatched command's dotted FQN
+      # @param result [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result]
+      #   the dispatch's own result
+      # @return [Hash{Symbol => Object}] the settled record's current state, read
+      #   back from the repository; `result.state` (or `{}`) when the result has no
+      #   id or the repository no longer has that aggregate/record
       def settled_state(runtime, verb, result)
         return result.state || {} unless result.respond_to?(:id) && result.id
 
@@ -202,13 +261,24 @@ module Hecks
       # expects a command's own declared attributes at the top level,
       # not a port operation's already-wrapped `to:`/`with:` shape.
       #
-      # This used to rely on `resolve_target` raising `UnknownVerb` for
-      # any port-operation verb — true only so long as nothing else ever
-      # asked it to resolve one. Now that a `policy` can legitimately
-      # `trigger` a port operation (`ReactionInvocation#resolve_target`'s
-      # own port-operation branch), that raise is gone, so this checks
-      # for a port operation directly instead of leaning on a refusal
-      # that no longer happens.
+      # Checks for a port operation directly rather than leaning on
+      # `resolve_target` to raise `UnknownVerb` for one — a refusal that held
+      # only so long as nothing else ever asked it to resolve a port-operation
+      # verb. Now that a `policy` can legitimately `trigger` a port operation
+      # (`ReactionInvocation#resolve_target`'s own port-operation branch),
+      # that raise no longer happens, so this checks directly instead.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the command's dotted FQN, or a port operation's
+      # @param args [Hash{Symbol => Object}] the command's (or setup's) facts, mixing
+      #   receiver identity and declared arguments
+      # @return [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
+      #   dispatch's own result
+      # @raise [Runtime::UnknownVerb] if `verb` is not fully qualified or names an
+      #   undeclared domain, aggregate, command, entity or port operation
+      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the
+      #   domain refuses the call
       def dispatch_command(runtime, verb, args)
         return runtime.dispatch_flat(verb, args) if port_operation?(runtime, verb)
 
@@ -231,6 +301,11 @@ module Hecks
       # `ReactionInvocation#resolve_target` both already check — a bare
       # domain/aggregate lookup plus a port-name lookup, no command
       # resolution needed since all this asks is whether one exists.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the verb to check, dotted FQN shaped
+      # @return [Boolean] true if `verb` names a port operation on a declared aggregate
       def port_operation?(runtime, verb)
         domain, aggregate_name, command_path = Naming.split_verb(verb)
         return false unless command_path
@@ -242,6 +317,13 @@ module Hecks
         rest && !!aggregate.port(head)
       end
 
+      # Runs the query under test and checks its `expect`.
+      #
+      # @param test [Behaviors::TestCase] the test case to run
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the suite's
+      #   booted runtime
+      # @param verb [String] the query's dotted FQN
+      # @return [Result] the test's pass or fail outcome
       def run_query(test, runtime, verb)
         rows = runtime.query(verb, **test.input)
 
@@ -267,6 +349,11 @@ module Hecks
         check_ok(test) || check_fields(test, row) || pass_result(test)
       end
 
+      # Whether `test.expect` names a field, not just one of the special keys.
+      #
+      # @param test [Behaviors::TestCase] the test case to check
+      # @return [Boolean] true if `test.expect` has any key besides `ok`, `refused`,
+      #   `emits` or `count`
       def field_expectations?(test)
         test.expect.keys.any? { |key| !SPECIAL_KEYS.include?(key) }
       end
@@ -277,6 +364,11 @@ module Hecks
       # ambiguous about which row it's describing. `check_fields` itself
       # stays row-shaped (it already is, for `run_command`'s settled
       # state); this picks which row it reads.
+      #
+      # @param test [Behaviors::TestCase] the test case, for the fail message
+      # @param rows [Array<Hash>, Hash] the query's own result
+      # @return [Hash, Result] `rows` itself when it isn't an Array; its one row when
+      #   it holds exactly one; otherwise a `fail_result` naming the row count
       def query_row(test, rows)
         return rows unless rows.is_a?(Array)
 
@@ -288,6 +380,11 @@ module Hecks
         end
       end
 
+      # Checks an `expect ok: true` expectation.
+      #
+      # @param test [Behaviors::TestCase] the test case to check
+      # @return [Result, nil] nil if `test.expect` has no `ok` key or expects `true`;
+      #   a `fail_result` if it names anything else
       def check_ok(test)
         return unless test.expect.key?(:ok)
 
@@ -297,6 +394,13 @@ module Hecks
         fail_result(test, "expect ok: only accepts true — got #{expected.inspect}")
       end
 
+      # Checks every field-name expectation in `test.expect` against `state`.
+      #
+      # @param test [Behaviors::TestCase] the test case to check
+      # @param state [Hash{Symbol, String => Object}] the settled record's (or query
+      #   row's) fields
+      # @return [Result, nil] nil if every expected field matches; a `fail_result` for
+      #   the first field that names none of `state`'s keys or doesn't match
       def check_fields(test, state)
         test.expect.each do |key, expected|
           next if SPECIAL_KEYS.include?(key)
@@ -314,6 +418,12 @@ module Hecks
         nil
       end
 
+      # Checks a caught domain refusal against `test.expect[:refused]`.
+      #
+      # @param test [Behaviors::TestCase] the test case to check
+      # @param error [StandardError] the caught refusal, a member of `REFUSAL_CLASSES`
+      # @return [Result] a `pass_result` if `test` expected this refusal's message, an
+      #   `error_result` if it expected none, or a `fail_result` if the message doesn't match
       def check_refusal(test, error)
         expected = test.expect[:refused]
         return error_result(test, "unexpected refusal (#{error.class}): #{error.message}") unless expected
@@ -333,6 +443,11 @@ module Hecks
       # field always comes back as a `Hecks::Runtime::Value`;
       # normalizing both sides to the same bare-scalar-or-plain-hash
       # shape is the one comparison that accepts either spelling.
+      #
+      # @param value [Object] a stored field's value, or an `expect` value to compare
+      #   it against
+      # @return [Object] the bare underlying value: unwrapped from a `Runtime::Value`,
+      #   or from a `{value: ...}` Hash; unchanged otherwise
       def normalize(value)
         return Hecks::Runtime::Value.materialize_unwrapped(value) if value.is_a?(Hecks::Runtime::Value)
         return normalize(value[:value]) if value.is_a?(Hash) && value.keys == [:value]
@@ -347,6 +462,15 @@ module Hecks
       # the tested command — `setup` never receives it, see the DSL
       # contract) narrows the search to one aggregate by name instead of
       # searching all of them.
+      #
+      # @param command [String, Symbol] a bare verb, or an already-dotted FQN
+      # @param on_aggregate [String, Symbol, nil] the aggregate to search, or nil to
+      #   search every aggregate of every bluebook
+      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted
+      # @param kind [Symbol] `:command` or `:query`
+      # @return [String] `command` unchanged if already dotted, otherwise its resolved
+      #   dotted FQN
+      # @raise [ArgumentError] if no aggregate declares `command`, or more than one does
       def qualify(command, on_aggregate, bluebooks, kind:)
         return command.to_s if command.to_s.include?(".")
 
@@ -354,9 +478,19 @@ module Hecks
         disambiguate_qualified_name(candidates, command, kind, bluebooks)
       end
 
+      # Finds every aggregate that could be what a bare command/query name refers to.
+      #
       # **The search** — every (bluebook, aggregate) pair that declares a
       # command/query named `command`, narrowed to `on_aggregate` by name
       # when given.
+      #
+      # @param command [String, Symbol] the bare verb to search for
+      # @param on_aggregate [String, Symbol, nil] the aggregate to search, or nil to
+      #   search every aggregate of every bluebook
+      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted
+      # @param kind [Symbol] `:command` or `:query`
+      # @return [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] every matching
+      #   (chapter, aggregate) pair
       def qualify_candidates(command, on_aggregate, bluebooks, kind)
         members = kind == :query ? :queries : :commands
         pairs =
@@ -368,9 +502,20 @@ module Hecks
         pairs.select { |_, agg| agg.public_send(members).any? { |m| m.hecks_name == command.to_s } }
       end
 
+      # Resolves a search's candidates to exactly one dotted FQN, or refuses.
+      #
       # **The report** — zero candidates and more-than-one candidates both
       # refuse (with a different message); exactly one resolves to its
       # dotted FQN.
+      #
+      # @param candidates [Array<Array(Bluebook::Chapter, Bluebook::Aggregate)>] the
+      #   matching (chapter, aggregate) pairs found by `qualify_candidates`
+      # @param command [String, Symbol] the bare verb that was searched for
+      # @param kind [Symbol] `:command` or `:query`, for the refusal message
+      # @param bluebooks [Array<Bluebook::Chapter>] every chapter the suite booted,
+      #   for the refusal message
+      # @return [String] the one candidate's dotted FQN
+      # @raise [ArgumentError] if `candidates` is empty, or holds more than one
       def disambiguate_qualified_name(candidates, command, kind, bluebooks)
         case candidates.size
         when 0
@@ -386,8 +531,24 @@ module Hecks
         end
       end
 
+      # Builds a passing result.
+      #
+      # @param test [Behaviors::TestCase] the test that passed
+      # @return [Result] a `:pass` result
       def pass_result(test) = Result.new(description: test.description, status: :pass, message: nil)
+
+      # Builds a failing result.
+      #
+      # @param test [Behaviors::TestCase] the test whose expectation was not met
+      # @param message [String] what was expected versus what happened
+      # @return [Result] a `:fail` result
       def fail_result(test, message)  = Result.new(description: test.description, status: :fail, message: message)
+
+      # Builds an errored result.
+      #
+      # @param test [Behaviors::TestCase] the test that could not run to a conclusion
+      # @param message [String] what went wrong
+      # @return [Result] an `:error` result
       def error_result(test, message) = Result.new(description: test.description, status: :error, message: message)
 
       Result = Struct.new(:description, :status, :message, keyword_init: true)

data/lib/hecks/behaviors/ir.rb

@@ -8,18 +8,29 @@
 # round-trip machinery a real bluebook construct does. It is a test
 # artifact a runner reads on demand, not a domain a boot needs.
 module Hecks
+  # The `.behaviors` toolkit: the DSL a `.behaviors` file is written against
+  # (`Hecks.behaviors`, dsl.rb), the plain-Struct IR it builds (this file), the runner
+  # that boots a suite's domain and checks each test (runner.rb, expectations.rb), and
+  # an rspec shim for a consuming app's own suite (rspec.rb).
   module Behaviors
     TestSetup = Struct.new(:command, :args, keyword_init: true)
 
     TestCase = Struct.new(:description, :tests_command, :on_aggregate, :kind,
                           :setups, :input, :expect, keyword_init: true) do
+      # Tells whether `tests_command` is already a fully qualified verb name.
+      #
       # An already-dotted tests_command is a literal FQN; otherwise `on:`
       # composes with the domain name resolved once setups/the tested
       # dispatch actually run (see Expectations — the domain isn't known
       # until `loads` is booted, so it's a runtime concern, not a field
       # here).
+      #
+      # @return [Boolean] true when `tests_command` contains a `.`
       def dotted? = tests_command.to_s.include?(".")
 
+      # Tells whether this test case exercises a query rather than a command.
+      #
+      # @return [Boolean] true when `kind` is `:query`
       def query? = kind == :query
     end
 

data/lib/hecks/behaviors/rspec.rb

@@ -21,6 +21,14 @@ module Hecks
     module RSpec
       module_function
 
+      # Parses one `.behaviors` file and registers an rspec example group for it, one
+      # `it` per test named by the test's own description.
+      #
+      # @param path [String] the `.behaviors` file's path
+      # @return [void]
+      # @raise [RuntimeError] not raised by this call itself; wraps `parsed.parse_error`'s
+      #   message and is raised only when rspec later runs the generated "loads without a
+      #   parse error" example, so it surfaces as that example's failure
       def describe_file(path)
         parsed = Behaviors.parse(path)
 

data/lib/hecks/behaviors/runner.rb

@@ -45,6 +45,10 @@ module Hecks
       # suite from whatever loaded before it in a sweep (a real bug in a
       # prior port of this idea: compared only against nil, so after the
       # first successful file in a sweep it stayed non-nil forever).
+      # @param path [String] the `.behaviors` file's path
+      # @return [Behaviors::ParseResult] `suite` holding the built `BehaviorsSuite` and
+      #   `parse_error` nil on success; `suite` nil and `parse_error` a String describing
+      #   a raised exception, or the file loading without calling `Hecks.behaviors`
       def parse(path)
         path = File.expand_path(path)
         previous_path = loading_path
@@ -66,6 +70,11 @@ module Hecks
       end
 
       # One `.behaviors` file → `FileResult`, every test actually run.
+      #
+      # @param path [String] the `.behaviors` file's path
+      # @return [Behaviors::FileResult] `parse_error` and empty `runs` on a parse
+      #   failure; otherwise `parse_error` nil and `runs` one `Expectations::Result`
+      #   per test
       def run(path)
         parsed = parse(path)
         return FileResult.new(path: parsed.path, parse_error: parsed.parse_error, runs: []) if parsed.parse_error
@@ -78,12 +87,22 @@ module Hecks
       # it actually found — a sweep that goes green without saying how
       # much it looked at is indistinguishable from one that found
       # nothing to look at.
+      #
+      # @param dir [String] the directory to search, recursively, for `.behaviors` files
+      # @return [Behaviors::SweepResult] `files_swept` the count found, `files` one
+      #   `FileResult` per file, and `summary` the aggregate counts `summarize` returns
       def run_all(dir)
         files = Dir.glob(File.join(dir, "**", "*.behaviors"))
         results = files.map { |path| run(path) }
         SweepResult.new(root: dir, files_swept: files.size, files: results, summary: summarize(results))
       end
 
+      # Tallies a sweep's results into counts by outcome.
+      #
+      # @param results [Array<Behaviors::FileResult>] the swept files' results
+      # @return [Hash{Symbol => Integer}] `:files` the file count, `:parse_errors` files
+      #   that failed to parse, `:total` tests actually run across every file, `:passed`,
+      #   `:failed` and `:errored` counting each `Expectations::Result#status`
       def summarize(results)
         runs = results.flat_map(&:runs)
         {

data/lib/hecks/behaviors.rb

@@ -13,6 +13,14 @@ module Hecks
     # behaviors suite is a test artifact a runner reads on demand, never
     # a thing a live domain boot needs, so it has no business landing in
     # `Runtime.current_registry`.
+    #
+    # @param name [String] the suite's declared name
+    # @yield the suite's body, evaluated against a `Behaviors::BehaviorsBuilder`
+    # @return [Behaviors::BehaviorsSuite] the built suite, also stashed as
+    #   `Behaviors.last_suite`
+    # @raise [Behaviors::LoadOutsideRunner] if called outside `Behaviors.run(path)`
+    # @raise [Behaviors::Malformed] if the suite declares no `vision` or `loads`, or
+    #   any of its `test` blocks is malformed
     def behaviors(name, &)
       path = Behaviors.loading_path or
         raise Behaviors::LoadOutsideRunner,

data/lib/hecks/bluebook/aggregate.rb

@@ -80,6 +80,36 @@ module Hecks
       # Assigns what the language declares, then hands off to the
       # behaviour's own `settle` — derived identity, name indexes and
       # owner stamping, none of which the declaration states.
+      #
+      # @param name [String, Symbol] the aggregate's declared name
+      # @param description [String, nil] the aggregate's declared prose description
+      # @param attributes [Array<Bluebook::Attribute>] the aggregate's declared fields
+      # @param value_objects [Array<Class>] the value object classes (`Bluebook::ValueObject`
+      #   subclasses) declared on this aggregate
+      # @param commands [Array<Class>] the command classes (`Bluebook::Command` subclasses)
+      #   declared on this aggregate
+      # @param invariants [Array<Bluebook::Invariant>] the aggregate-level rules that must
+      #   always hold
+      # @param preconditions [Array<Bluebook::Given>] the aggregate's own named `given`s, a
+      #   referencing command's own resolved `givens` entry can point back at
+      # @param projected_fields [Array<Bluebook::ProjectedField>] the declared `projects`
+      #   fields, copied from another aggregate's own state by the rebuild sweep
+      # @param identified_by [String, Symbol, Array<String, Symbol>] the identity path(s)
+      #   this aggregate is addressed by
+      # @param lifecycle [Bluebook::Lifecycle, nil] the aggregate's declared state machine,
+      #   or `nil` if it declares none
+      # @param entities [Array<Class>] the entity classes (`Bluebook::Entity` subclasses)
+      #   nested directly under this aggregate
+      # @param queries [Array<Bluebook::Query>] the queries declared directly on this
+      #   aggregate
+      # @param policies [Array<Bluebook::Policy>] the reactions hoisted onto this aggregate
+      #   from the chapter that assembled it
+      # @param ports [Array<Bluebook::DomainPort>] the aggregate-scoped ports attached after
+      #   this aggregate was built
+      # @param reference_targets [Array<String>] the name of every aggregate this one points
+      #   at with an aggregate-level `reference_to`
+      # @param provenance [Object, nil] the aggregate's declared canonical source, captured
+      #   exactly as written, or `nil` if it declares none
       def initialize(name:, description: nil, attributes: [], value_objects: [],
                      commands: [], invariants: [], preconditions: [], projected_fields: [], identified_by: [], lifecycle: nil,
                      entities: [], queries: [], policies: [], ports: [], reference_targets: [],

data/lib/hecks/bluebook/assembly/aggregate_assembly.rb

@@ -10,10 +10,17 @@ module Hecks
       # It decides nothing. Whether a declaration is admissible was settled on the
       # way in, by the language.
       class AggregateAssembly
+        # @param row [Hash{Symbol => Object}] one declared aggregate's raw contract data,
+        #   as `@declaration[:aggregates]` carries it
         def initialize(row)
           @row = row
         end
 
+        # Builds the aggregate's whole owner-chain graph — its value objects, commands,
+        # entities, queries and lifecycle — from its raw declaration.
+        #
+        # @return [Bluebook::Aggregate] the built aggregate, with every reference stamped
+        #   to resolve against it
         def aggregate
           shapes   = Array(@row[:value_objects]).map { |shape| value_object(shape) }
           commands = Array(@row[:commands]).map { |verb| Build.call("Command", verb) }

data/lib/hecks/bluebook/assembly/build.rb

@@ -3,10 +3,10 @@ module Hecks
     class Assembly
       # One way to build a construct, for every construct.
       #
-      # There used to be a method per category here — `value_object(row)`,
-      # `command(row)`, `policy(row)` — each one gathering the same keywords the
-      # contract already names. This reads the contract instead, so adding a field
-      # to the language and forgetting to assemble it is caught by the coverage gate
+      # Not a method per category — `value_object(row)`, `command(row)`,
+      # `policy(row)`, each gathering the same keywords the contract already
+      # names. This reads the contract instead, so adding a field to the
+      # language and forgetting to assemble it is caught by the coverage gate
       # rather than by nobody.
       #
       # `make` is the only branch, and it is a real one: a construct that became a
@@ -16,6 +16,16 @@ module Hecks
       module Build
         module_function
 
+        # Builds one construct from its declared row, reading which keywords it takes
+        # and how to read each one off `Assembly.contract(category)`.
+        #
+        # @param category [String] the contract's category name, such as `"Aggregate"`
+        #   or `"Command"`
+        # @param row [Hash{Symbol => Object}] the construct's own declared row
+        # @param extra [Hash{Symbol => Object}] keywords the caller supplies directly,
+        #   such as already-built children the contract itself cannot derive
+        # @return [Object] the built construct: an instance for a category whose
+        #   `make` is `:new`, or a class for one whose `make` is `:declare`
         def call(category, row, extra = {})
           contract = Assembly.contract(category)
           keywords = contract.fields.to_h { |keyword, (key, reader)| [keyword, read(reader, row[key])] }
@@ -23,12 +33,23 @@ module Hecks
           holder(contract).public_send(contract.make, **keywords, **extra)
         end
 
+        # Resolves the class or module a contract's construct is built through.
+        #
+        # @param contract [Bluebook::Assembly::Contract] the category's field contract
+        # @return [Module] the holder that answers `contract.make` (`.new` or `.declare`)
+        # @raise [ArgumentError] if the contract names no holder to build through
         def holder(contract)
           contract.holder or raise ArgumentError, "#{contract} holds nothing that can be built"
         end
 
         # A reader is a Marks method, a list of them, or one of three spellings that
         # need no decoding at all.
+        #
+        # @param reader [Symbol, Array, nil] the contract field's reader: `:plain`,
+        #   `:identity`, `:flag`, `[:each, marks_method]`, `[:option, name]`, or a bare
+        #   `Marks` method name
+        # @param value [Object] the raw declared value to read
+        # @return [Object] the value read through `reader`
         def read(reader, value)
           case reader
           when :plain    then value