hecks 1.3.0 → 1.5.0

data/lib/hecks/query_specification/field_path.rb

@@ -1,20 +1,21 @@
 module Hecks
   module QuerySpecification
-    # ONE reading of a dotted query-field path, shared by every place that
-    # used to invent its own. The reference interpreter did a bare
-    # `record[field]` lookup (a dotted path silently matched nothing), the
-    # SQL side split dots but judged numericness from the FIRST nested
-    # segment only (a two-level path quietly compared text), and the build
-    # seal walked the declaration graph a third way. Three
-    # implementations of "what does pizza.price_cents.cents mean" is two
-    # more than a language gets to have.
+    # One reading of a dotted query-field path, shared by every place that
+    # would otherwise invent its own. Left to themselves they disagree: a
+    # reference interpreter doing a bare `record[field]` lookup silently
+    # matches nothing for a dotted path, an SQL side that splits dots but
+    # judges numericness from the first nested segment only quietly
+    # compares a two-level path as text, and a build seal walks the
+    # declaration graph a third way. Three implementations of "what does
+    # pizza.price_cents.cents mean" is two more than a language gets to
+    # have.
     #
     # Two sides, deliberately in one file so they cannot drift:
     #
-    #   dig(holder, field)        — VALUE side: walk a record's held state,
+    #   dig(holder, field)        — value side: walk a record's held state,
     #                               segment by segment, through Value
     #                               objects and plain hashes alike.
-    #   leaf_attribute / numeric? — DECLARATION side: walk the declared
+    #   leaf_attribute / numeric? — declaration side: walk the declared
     #                               shape to the attribute a path lands on.
     #                               Callers supply value-object lookup as a
     #                               block, because an Aggregate and a
@@ -26,22 +27,39 @@ module Hecks
       NUMERIC_PRIMITIVES = %w[Integer Float].freeze
       SCALAR_PRIMITIVES  = %w[String Integer Float TrueClass FalseClass].freeze
 
+      # Reads the value a dotted field path names out of a record's held state.
+      #
       # The held value a dotted field names, or nil — never a raise. The
       # first segment reads off the record (an Instance, a Value, or a
       # plain row hash); the rest read through whatever each step holds. A
       # stored nested value object is a plain hash by the time it is read
       # back, keyed by symbol in memory and by string off a wire decode,
       # so both spellings are tried — `key?` first, never `||`, because
-      # `||` falls through a genuinely-stored `false` to the OTHER
+      # `||` falls through a genuinely-stored `false` to the other
       # spelling (usually absent) and returns `nil` instead. The seal
       # admits boolean leaves (`SCALAR_PRIMITIVES` below), so a `false`
       # here is a real, held answer, not a missing one.
+      #
+      # @param holder [Runtime::Instance, Runtime::Value, Hash, nil] the record, value
+      #   object or row Hash the first segment is read from
+      # @param field [String, Symbol, nil] the path, segments separated by `.`, such as
+      #   `"price.cents"`; a bare field name is a one-segment path
+      # @return [Object, nil] the value held at the end of the path; `nil` when `field` is
+      #   `nil`, a segment is absent, or a step lands on `nil` or an Array
       def dig(holder, field)
         return nil if field.nil?
 
         field.to_s.split(".").reduce(holder) { |current, segment| read(current, segment) }
       end
 
+      # Reads one path segment off whatever the previous step held — a single
+      # step of `dig`.
+      #
+      # @param current [Runtime::Instance, Runtime::Value, Hash, Array, nil] the value the
+      #   walk has reached; a Hash is tried by Symbol key, then by String key
+      # @param segment [String] one segment of the dotted path
+      # @return [Object, nil] the member named `segment`; `nil` when `current` is `nil` or
+      #   an Array, or holds no such member
       def read(current, segment)
         return nil if current.nil?
 
@@ -54,7 +72,7 @@ module Hecks
         # an Array broke it: `Array#[]` demands an Integer index, so
         # `current[segment]` (a String) raised `TypeError` straight
         # through `dig` instead of answering nil. A dotted path stepping
-        # INTO a list_of attribute (`where "tags.name" == "x"` against a
+        # into a list_of attribute (`where "tags.name" == "x"` against a
         # bare list, rather than each element) has no single member a
         # bare index would name anyway — nil is the honest answer, the
         # same one a dangling reference or a missing key already gets.
@@ -63,11 +81,23 @@ module Hecks
         current[segment]
       end
 
+      # Walks the declared shape to the attribute a dotted path lands on.
+      #
       # The declared attribute a path lands on, or nil. `segments` is the
       # dotted tail — for a bare field it is empty and the root attribute
       # is its own leaf. The walk stops dead at a reference (an id is a
       # scalar; nothing nests under it) and at any member the declared
       # value object does not carry.
+      #
+      # @param attribute [Bluebook::Attribute, nil] the root attribute the path's first
+      #   segment names; `nil` (no such attribute) answers `nil`
+      # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
+      # @yield looks a value object up by name in the caller's own declarations
+      # @yieldparam type [String] the type name of the attribute being stepped into
+      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil` when
+      #   the type is not a value object the caller knows
+      # @return [Bluebook::Attribute, nil] the attribute at the end of the path; `nil` when
+      #   a step crosses a reference, an undeclared type or a member that does not exist
       def leaf_attribute(attribute, segments)
         current = attribute
         segments.each do |segment|
@@ -79,12 +109,24 @@ module Hecks
         current
       end
 
+      # Decides from the declared shape whether a field path holds a number.
+      #
       # May an ordered comparator (lt/lte/gt/gte) land here, and may an
-      # ORDER BY cast here numerically? A bare field keeps the one-level
+      # `ORDER BY` cast here numerically? A bare field keeps the one-level
       # convention every adapter already implements: a numeric primitive,
       # or a value object carrying at least one numeric member. A dotted
       # path must land on a numeric primitive itself — the convention does
-      # not reach through a named path, it IS the absence of one.
+      # not reach through a named path, it is the absence of one.
+      #
+      # @param attribute [Bluebook::Attribute, nil] the root attribute the path starts at;
+      #   `nil` answers `false`
+      # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
+      # @yield looks a value object up by name, as for `leaf_attribute`
+      # @yieldparam type [String] the type name to look up
+      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil`
+      # @return [Boolean] `true` when the leaf is an `Integer` or `Float`, or a bare field
+      #   naming a value object with at least one such member; `false` for a list, a
+      #   reference, or a path that lands nowhere
       def numeric?(attribute, segments, &)
         leaf = leaf_attribute(attribute, segments, &)
         return false if leaf.nil? || leaf.list? || leaf.reference?
@@ -95,9 +137,21 @@ module Hecks
         !shape.nil? && shape.attributes.any? { |member| NUMERIC_PRIMITIVES.include?(member.type.to_s) }
       end
 
-      # A dotted path must end on a SCALAR member — landing on a value
+      # Decides whether a path ends on a scalar primitive that every engine
+      # compares the same way.
+      #
+      # A dotted path must end on a scalar member — landing on a value
       # object would hand SQL a JSON object where the reference
       # interpreter unwraps a hash, and the two would answer differently.
+      #
+      # @param attribute [Bluebook::Attribute, nil] the root attribute the path starts at;
+      #   `nil` answers `false`
+      # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
+      # @yield looks a value object up by name, as for `leaf_attribute`
+      # @yieldparam type [String] the type name to look up
+      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil`
+      # @return [Boolean] `true` when the leaf is a non-list, non-reference attribute typed
+      #   `String`, `Integer`, `Float`, `TrueClass` or `FalseClass`
       def scalar_leaf?(attribute, segments, &)
         leaf = leaf_attribute(attribute, segments, &)
         !leaf.nil? && !leaf.list? && !leaf.reference? && SCALAR_PRIMITIVES.include?(leaf.type.to_s)

data/lib/hecks/query_specification/hop_path.rb

@@ -2,25 +2,25 @@ require_relative "../naming"
 
 module Hecks
   module QuerySpecification
-    # ONE reading of a dotted query-field path that hops THROUGH a
+    # One reading of a dotted query-field path that hops through a
     # reference into another aggregate's own shape — FieldPath's
-    # sibling, not its member. FieldPath walks a SHAPE, which cannot
+    # sibling, not its member. FieldPath walks a shape, which cannot
     # loop, and answers nil, never raising, because there is nothing
-    # left to say beyond "not found." HopPath walks the REFERENCE
-    # GRAPH instead — `BluebookBuilder#validate_no_bidirectional_references!`
-    # refuses any reference CYCLE at declaration time (ADR 0025,
+    # left to say beyond "not found." HopPath walks the reference
+    # graph instead — `BluebookBuilder#validate_no_bidirectional_references!`
+    # refuses any reference cycle at declaration time (ADR 0025,
     # "References" — widened from a direct pair to any ring, DFS over
     # the chapter's own reference graph), so what's left to guard here
     # is depth, not cycles: MAX_HOPS below, and this module's own
     # `refusal` states for a target the chapter doesn't resolve. A walk
-    # here still needs to say WHY it stopped, not just that it did.
+    # here still needs to say why it stopped, not just that it did.
     #
-    # Every method below takes an ATTRIBUTE ARRAY, never a "shape"
+    # Every method below takes an attribute array, never a "shape"
     # object — deliberately, because the two real callers hold their
     # attributes differently. `AggregateBuilder` (tier-1 seal, mid-
     # build) exposes `attributes` as a plain reader, but its own
     # `attribute(name, type = String, ...)` is the DSL's attribute-
-    # DECLARING method — calling it as a finder would silently mint a
+    # declaring method — calling it as a finder would silently mint a
     # new String attribute instead of looking one up. A sealed
     # `Aggregate` (tier-2 seal, and every runtime target) has a
     # real `attribute(name)` finder, but taking the array either way
@@ -37,37 +37,51 @@ module Hecks
       Plan = Struct.new(:hops, :tail, :refusal, keyword_init: true)
 
       # A hop chain long enough to matter is long enough to be a
-      # mistake — NOT a guard against a walk that cannot terminate.
+      # mistake — not a guard against a walk that cannot terminate.
       # Nothing here loops forever regardless of how the reference
       # graph is shaped: a hop chain is a literal dotted string, fixed
       # at declaration time, and every step consumes exactly one of
-      # its own segments — the walk is bounded by what was TYPED, not
+      # its own segments — the walk is bounded by what was typed, not
       # by the graph. A self-referential aggregate hopping through
       # itself more than once (`"parent.parent.name"`, a grandparent
       # query) is real, common, and perfectly safe; this exists only
       # to refuse a chain nobody meant to write this long.
       MAX_HOPS = 8
 
+      # Names the path segment a reference attribute answers to.
+      #
       # The segment name a Reference answers to in a hop path — its own
       # declared attribute name, unchanged (ADR 0025, "References":
-      # `reference_to` mints that bare name now, no `_id`, so there is
+      # `reference_to` mints that bare name, no `_id`, so there is
       # no derivation left to apply). `proposal/client` (a query hop)
       # and `proposal.client` (the Ruby accessor,
       # `Facade::Handle#define_reference_accessors`) name the same
       # concept the same way.
+      #
+      # @param attribute [Bluebook::Attribute] a reference-typed attribute
+      # @return [String] the attribute's declared name
       def hop_name(attribute) = attribute.name.to_s
 
-      # Does this path's HEAD cross into another record via `/`? THE
-      # OPERATOR IS THE ANSWER NOW, not a name collision to arbitrate —
+      # Decides whether a field path starts by hopping through one of the given
+      # references, without resolving the reference's target.
+      #
+      # Does this path's head cross into another record via `/`? The
+      # operator is the answer now, not a name collision to arbitrate —
       # `.` walks fields inside this record, `/` crosses into another
       # one, so a path with no `/` is never a hop, full stop, and the
-      # OLD "a real local attribute wins first" rule (needed only
+      # old "a real local attribute wins first" rule (needed only
       # because `.` was overloaded for both meanings, and `client_id`
       # vs `client` was how the two were told apart) has nothing left
       # to arbitrate. Answerable from `attributes` alone — a Reference
       # knows its own `target_name` at declaration, before it can
-      # `resolve` it — which is what lets the AGGREGATE seal recognise
+      # `resolve` it — which is what lets the aggregate seal recognise
       # a hop it cannot yet check.
+      #
+      # @param field [String, Symbol] the query field path, such as `:"client/status"`
+      # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
+      #   starts from
+      # @return [Boolean] `true` when the path has a `/` and the segment before the first
+      #   one names a reference attribute
       def hop_head?(field, attributes)
         head, rest = field.to_s.split("/", 2)
         return false unless rest
@@ -75,16 +89,27 @@ module Hecks
         attributes.any? { |candidate| candidate.reference? && hop_name(candidate) == head }
       end
 
-      # ONE STEP: does `field`'s head hop through one of `attributes`'
+      # Resolves the first hop of a field path and hands back what is left to walk.
+      #
+      # **One step**: does `field`'s head hop through one of `attributes`'
       # own references? Answers the resolved `Hop` plus the string
       # still left to walk (itself possibly another `/`-hop, against
-      # the TARGET's own attributes, or a plain `.`-dotted field walk
+      # the target's own attributes, or a plain `.`-dotted field walk
       # once the hops run out) — or nil, when the head names nothing or
       # the path has no `/` at all. This is the one primitive
       # Runtime::ReferenceHop needs: it recurses hop by hop through its
       # own `apply`, one ordinary same-aggregate query at a time, and
       # never needs the whole chain resolved up front the way a seal
       # does.
+      #
+      # @param field [String, Symbol] the query field path, such as `"client/region/name"`
+      # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
+      #   starts from
+      # @return [Array(Hop, String), nil] the hop and the rest of the path after the first
+      #   `/`; the hop's `target` is `nil` when the referenced aggregate is not in the
+      #   declaring chapter. `nil` when the path has no `/` or its head names no reference
+      # @raise [Bluebook::DSL::Malformed] if the reference has no `declared_in` aggregate
+      #   to resolve its target through
       def next_hop(field, attributes)
         head, rest = field.to_s.split("/", 2)
         return nil unless rest
@@ -96,10 +121,22 @@ module Hecks
         [hop, rest]
       end
 
-      # The WHOLE chain, resolved — every hop's target found, in
+      # Resolves every hop of a field path in order, stopping with a reason at
+      # the first one it cannot follow.
+      #
+      # The whole chain, resolved — every hop's target found, in
       # order — for the one caller that needs it all at once:
-      # BluebookBuilder#validate_query_hops!, checking a hop chain
+      # `BluebookBuilder#validate_query_hops!`, checking a hop chain
       # before anything ever dispatches it.
+      #
+      # @param field [String, Symbol] the query field path, such as `"client/region/name"`
+      # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
+      #   starts from
+      # @return [Plan] `hops` walked so far; `tail` the remaining `.`-dotted field (`nil`
+      #   on refusal); `refusal` `nil` when clean, `:unresolvable` when the last hop's
+      #   target is not found, `:too_deep` when the chain exceeds `MAX_HOPS`
+      # @raise [Bluebook::DSL::Malformed] if a reference on the path has no `declared_in`
+      #   aggregate to resolve its target through
       def plan(field, attributes)
         hops = []
         remaining = field.to_s
@@ -113,7 +150,7 @@ module Hecks
           return Plan.new(hops: hops, tail: nil, refusal: :too_deep) if hops.size >= MAX_HOPS
 
           # Pushed even unresolved — a caller reporting :unresolvable
-          # needs THIS hop's own target_name (real, known at
+          # needs this hop's own target_name (real, known at
           # declaration, regardless of whether resolve succeeded), not
           # whatever hop came before it. `.target` is nil on this one
           # entry; every caller checking `hops.last.target` already has

data/lib/hecks/query_specification/read_model/specification.rb

@@ -9,6 +9,10 @@ module Hecks
       class Specification < Common::Options
         attr_reader :joins
 
+        # @param joins [Array<Hash{Symbol => Object}>] one row per projected aggregate head,
+        #   keyed `:aggregate` (String target name), `:as` (Symbol output name) and `:many`
+        #   (Boolean), as `ReadModelBuilder` builds them
+        # @param ** [Hash] the shared query options, passed to `Common::Options#initialize`
         def initialize(joins: [], **)
           super(**)
           @joins = joins

data/lib/hecks/rendering.rb

@@ -1,8 +1,8 @@
 require "json"
 
 module Hecks
-  # HOW A VALUE READS INSIDE A REFUSAL, in one place, because a refusal is an
-  # ANSWER and its wording is contract — pinned byte-for-byte by the corpus.
+  # How a value reads inside a refusal, in one place, because a refusal is an
+  # answer and its wording is contract — pinned byte-for-byte by the corpus.
   #
   # `inspect` and JSON agree on scalars and disagree on everything composite :
   # a hash is `{"cents"=>100}` against `{"cents":100}`, an array is `["a", "b"]`
@@ -17,6 +17,12 @@ module Hecks
   module Rendering
     module_function
 
+    # Renders a value the way it should read inside a refusal message.
+    #
+    # @param value [Object] the value to render
+    # @return [String] `"nil"` for nil, JSON for a Hash/Array or a duck-typed value
+    #   object (unwrapped to its bare scalar when it has exactly one field), or
+    #   `value.inspect` for anything else
     def describe(value)
       case value
       when nil then "nil"
@@ -29,7 +35,7 @@ module Hecks
         # ("#<Hecks::Runtime::Value:0x...>") into an otherwise
         # correct domain refusal. Duck-typed on `respond_to?(:to_h)`
         # rather than naming `Runtime::Value` directly — `Runtime::Value`
-        # itself requires THIS file (`runtime/value.rb`'s own
+        # itself requires this file (`runtime/value.rb`'s own
         # `require_relative "../rendering"`), so naming it here would be
         # circular. A single-field wrapper (the overwhelming common case
         # — an amount, an id, a lifecycle field) unwraps to its bare

data/lib/hecks/router/namespace_installer.rb

@@ -12,6 +12,13 @@ module Hecks
       # to the router, pinned to this specific FQN version rather than
       # the router's default resolution.
       class OptionsProxy
+        # @param router [Router] router to dispatch resolved calls through
+        # @param realm [String, nil] realm segment of the FQN this proxy pins
+        # @param domain [String] domain segment of the FQN this proxy pins
+        # @param aggregate [String, nil] aggregate segment, or nil for a domain-level query
+        # @param options [Hash{Symbol => Object}] the `.options(...)` call's keywords; only
+        #   `:version` is accepted
+        # @raise [ArgumentError] if `options` has a key other than `:version`
         def initialize(router:, realm:, domain:, aggregate:, options:)
           unknown = options.keys - [:version]
           raise ArgumentError, "unknown router options: #{unknown.join(', ')}" unless unknown.empty?
@@ -45,10 +52,16 @@ module Hecks
         end
       end
 
+      # @param router [Router] router whose current routes get Ruby constants and methods
       def initialize(router)
         @router = router
       end
 
+      # Installs every current-version route as a namespace constant/method,
+      # plus the aggregate `find`/`all`/`count`/`events`/`repository` door and
+      # short `Aggregate.verb` shortcuts.
+      #
+      # @return [self]
       def install!
         current_entries.each { |entry| install_namespace_entry(entry) }
         install_shortcuts!
@@ -77,16 +90,16 @@ module Hecks
         end
       end
 
-      # `.find`/`.all`/`.count`/`.events`/`.repository` — the SAME read/CRUD
+      # `.find`/`.all`/`.count`/`.events`/`.repository` — the same read/CRUD
       # surface `Facade::Surface::AggregateDoor` gives a plain `Hecks
       # .boot`, missing here until now: `install_namespace_entry` above
-      # installs ONE method per declared VERB, so an aggregate with no
+      # installs one method per declared verb, so an aggregate with no
       # commands or queries of its own shape (or simply never asked for
       # a `find`-shaped query) had no way to look up one record by id
       # through the router surface at all — real gap, hit live building
       # a `List` aggregate meant to be read this way. Grouped by
       # (realm, domain, aggregate) rather than installed per-verb,
-      # because unlike a command or query this is the SAME five methods
+      # because unlike a command or query this is the same five methods
       # regardless of which verb happened to trigger this aggregate's
       # own namespace module into existing.
       def install_aggregate_doors!

data/lib/hecks/router.rb

@@ -9,31 +9,60 @@ module Hecks
 
     attr_reader :register
 
+    # Loads a project's bluebooks and builds a router over them, without
+    # installing any Ruby namespace shortcuts.
+    #
+    # @param root [String] project root to discover bluebooks under
+    # @return [Router] the built router
     def self.load(root) = new(Bluebook::ProjectLoader.load(root))
 
     # Install one project router for ordinary application calls. The explicit
     # `Router.load` API remains useful for tests and embedded hosts.
+    #
+    # @param root [String] project root to discover bluebooks under
+    # @return [Router] the booted router, also stored as `.default`
     def self.boot(root)
       router = load(root)
       router.install_namespace!
       @default = router
     end
 
+    # The process-wide router `.boot` installed.
+    #
+    # @return [Router] the router `.boot` installed
+    # @raise [NotBooted] if `.boot` has not been called yet
     def self.default
       @default || raise(NotBooted, "no project router is booted — call Hecks::Router.boot(root) first")
     end
 
+    # (see #dispatch)
     def self.dispatch(address, **args) = default.dispatch(address, **args)
+    # (see #query)
     def self.query(address, **args)    = default.query(address, **args)
 
+    # @param register [Bluebook::ProjectRegister, Bluebook::ProjectLoader] the FQN
+    #   catalogue to resolve addresses against
     def initialize(register)
       @register = register
     end
 
+    # Lists every routed FQN entry.
+    #
+    # @return [Array<Bluebook::ProjectRegister::Entry>] every routed FQN entry
     def available = register.entries.values
 
+    # Installs Ruby namespace constants and shortcut methods for every
+    # current-version route.
+    #
+    # @return [NamespaceInstaller] the installer that performed the install
     def install_namespace! = NamespaceInstaller.new(self).install!
 
+    # Resolves an address to its routed FQN entry.
+    #
+    # @param address [String] a fully-qualified command or query address, realm included
+    # @return [Bluebook::ProjectRegister::Entry] the routed entry
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [Fqn::Invalid] if `address` is not a well-formed FQN
     def resolve(address)
       fqn = Fqn.parse(address)
       raise UnknownAddress, "router addresses require a realm: #{address.inspect}" unless fqn.realm
@@ -43,13 +72,39 @@ module Hecks
       raise UnknownAddress, "no Bluebook route for #{address.inspect}"
     end
 
+    # Dispatches a command to its resolved aggregate.
+    #
+    # @param address [String] a fully-qualified command address, realm included
+    # @param args [Hash] command facts, plus the dispatcher's optional `:to`, `:with`,
+    #   and `:saga_correlation` keys
+    # @return [Runtime::Dispatcher::Result] the dispatch result
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [WrongVerbKind] if `address` names a query
+    # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
+    # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the domain refuses
+    #   the call
+    # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every retry
+    # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def dispatch(address, **args)
       entry = resolve(address)
       raise WrongVerbKind, "#{address.inspect} names a query; use #query" unless entry.command?
 
-      entry.dispatcher.dispatch(local_verb(entry), **args)
+      entry.dispatcher.dispatch_flat(local_verb(entry), args)
     end
 
+    # Queries a resolved aggregate, entity, or read model.
+    #
+    # @param address [String] a fully-qualified query address, realm included
+    # @param args [Hash{Symbol => Object}] the query's declared arguments
+    # @return [Array<Hash>] one row Hash per match; see `Runtime::Dispatcher#query`
+    #   for the exact shape per address kind
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [WrongVerbKind] if `address` names a command
+    # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
+    # @raise [Runtime::NotFound] if a read model's root reference names no record
+    # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
+    # @raise [KeyError] if a rooted read model is asked without its reference argument
+    # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def query(address, **args)
       entry = resolve(address)
       raise WrongVerbKind, "#{address.inspect} names a command; use #dispatch" unless entry.query?

data/lib/hecks/runtime/aggregate_lock.rb

@@ -1,40 +1,49 @@
 module Hecks
   module Runtime
-    # A PROCESS-WIDE, STRIPED MUTEX REGISTRY — the concurrency-control
-    # mechanism for every adapter that does NOT declare
+    # **A process-wide, striped mutex registry** — the concurrency-control
+    # mechanism for every adapter that does not declare
     # `:optimistic_concurrency` (Heki, Memory today; see
     # `CommandInterpreter#call`/`EntityInterpreter#call`, which choose
     # between this and Postgres's CAS+retry purely off
     # `repository.capabilities`).
     #
-    # WHY A LOCK SUFFICES HERE AND CAS IS NOT NEEDED: both adapters hold
+    # Why a lock suffices here and CAS is not needed: both adapters hold
     # process-local data. `Adapters::Memory.tenant_capable?`'s own comment
     # states the confirmed fact this relies on — two `Runtime.boot` calls
-    # get two entirely separate adapter instances; there is never a SECOND
-    # PROCESS writing the same Heki file or the same Memory Hash, only
-    # possibly other THREADS within this one process. A `Mutex` held for
+    # get two entirely separate adapter instances; there is never a second
+    # process writing the same Heki file or the same Memory Hash, only
+    # possibly other threads within this one process. A `Mutex` held for
     # the full hydrate-through-save critical section closes the identical
     # lost-update gap CAS closes for Postgres, with no schema, no version
     # column, and no retry loop — the second thread simply doesn't start
     # its own hydrate until the first thread's save has landed.
     #
-    # STRIPED, NOT ONE GLOBAL LOCK: keyed by `[domain, aggregate.hecks_name,
-    # id]`, so two dispatches against two DIFFERENT records never block
+    # **Striped, not one global lock**: keyed by `[domain, aggregate.hecks_name,
+    # id]`, so two dispatches against two different records never block
     # each other. The registry Hash itself is guarded by its own top-level
     # Mutex only for the moment a new per-key Mutex is created — two
-    # threads locking DIFFERENT keys for the first time never wait on one
+    # threads locking different keys for the first time never wait on one
     # another beyond that brief creation window.
     module AggregateLock
       @registry_lock = Mutex.new
       @locks = {}
 
       class << self
+        # Returns the Mutex striped to one record, creating it on first use.
+        #
         # `AggregateLock.for(domain, aggregate, id).synchronize { ... }`
         # `id: nil` — identity could not be resolved yet (see
-        # `Identity.best_effort`) — locks by aggregate TYPE alone, coarser
+        # `Identity.best_effort`) — locks by aggregate type alone, coarser
         # (every record of this aggregate serializes against every other)
-        # but still correct: it can only ever make dispatch MORE
+        # but still correct: it can only ever make dispatch more
         # conservative than a resolved id would.
+        #
+        # @param domain [String] the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate being dispatched
+        # @param id [String, nil] the resolved record id, or nil to stripe by aggregate type
+        #   alone
+        # @return [Mutex] the mutex for this `[domain, aggregate, id]` key, held for the full
+        #   hydrate-through-save critical section
         def for(domain, aggregate, id = nil)
           key = id.nil? ? [domain.to_s, aggregate.hecks_name] : [domain.to_s, aggregate.hecks_name, id.to_s]
           @registry_lock.synchronize { @locks[key] ||= Mutex.new }

data/lib/hecks/runtime/boot_gates.rb

@@ -1,8 +1,8 @@
 module Hecks
   module Runtime
     # A boot's own small set of phase-tagged, conditionally-present gates —
-    # ADR 0031. Registration is instance-scoped, ONE PER `Loader.boot`
-    # CALL, never a module-level singleton: a process that boots more than
+    # ADR 0031. Registration is instance-scoped, one per `Loader.boot`
+    # call, never a module-level singleton: a process that boots more than
     # one registry in its lifetime (every spec suite does) must never let
     # one boot's capability profile leak into the next boot's gate list.
     #
@@ -13,26 +13,44 @@ module Hecks
     # order — today exactly one gate per phase, so ordering among
     # same-phase gates has never been exercised.
     #
-    # This is deliberately NOT the same registry `Hecks::Projector` uses
+    # This is deliberately not the same registry `Hecks::Projector` uses
     # (ADR 0027) — that one is a process-wide, static IR-in/artifact-out
     # registry with no bindings and no live-state mutation; this one is
     # per-boot and gates real I/O (a Postgres mint, a saga-store read).
     # Sharing a primitive between them is deferred until a third consumer
     # actually wants it (0031's own Rejected Alternatives).
     class BootGates
+      # @return [void]
       def initialize
         @gates = Hash.new { |h, k| h[k] = [] }
       end
 
+      # Adds a gate to `phase`, run in registration order alongside any other gate there.
+      #
+      # @param name [Symbol] the gate's name, checked by `registered?`
+      # @param gate [Proc, Method] the gate; called as `gate.call(registry, directory)`
+      # @param phase [Symbol] the phase this gate runs under, such as `:pre_verify` or
+      #   `:post_verify`
+      # @return [Hecks::Runtime::BootGates] self, for chaining
       def register(name, gate, phase:)
         @gates[phase] << [name, gate]
         self
       end
 
+      # Reports whether a gate named `name` has been registered, under any phase.
+      #
+      # @param name [Symbol] the gate name to look for, across every phase
+      # @return [Boolean] true if a gate named `name` was registered under any phase
       def registered?(name)
         @gates.values.flatten(1).any? { |registered_name, _gate| registered_name == name }
       end
 
+      # Runs every gate registered under `phase`, in registration order.
+      #
+      # @param phase [Symbol] the phase to run, such as `:pre_verify` or `:post_verify`
+      # @param registry [Runtime::Registry] the booted registry, passed to each gate
+      # @param directory [String] the boot directory, passed to each gate
+      # @return [void]
       def run!(phase, registry, directory)
         @gates[phase].each { |pair| pair.last.call(registry, directory) }
       end