hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/pattern_subset.rb

@@ -1,24 +1,24 @@
 module Hecks
   module Bluebook
-    # WHICH REGEXES A BLUEBOOK MAY SAY.
+    # **Which regexes a bluebook may say**.
     #
     # A `pattern:` is a fact about a value, carried in a bluebook — declared
     # data, not Ruby code, so it must not lean on what any one engine happens
     # to accept. Regex engines disagree in two different ways :
     #
-    #   ONLY A BACKTRACKING ENGINE CAN MATCH IT — lookahead, lookbehind,
+    #   only a backtracking engine can match it — lookahead, lookbehind,
     #   backreferences, atomic groups, possessive quantifiers. None of these
     #   can be matched in linear time, and linear-time engines refuse them
     #   outright. Refused here for the same reason.
     #
-    #   EVERY ENGINE PARSES IT AND THEY MEAN DIFFERENT THINGS — the dangerous
+    #   every engine parses it and they mean different things — the dangerous
     #   half, because nothing errors. `\d` `\w` `\s` are ASCII in some engines
     #   and Unicode in others ; `[:digit:]` and friends flip the same way in
     #   the other direction. Both families are refused, and a domain spells
     #   the range it means.
     #
     # What remains — explicit ranges, alternation, quantifiers, anchors,
-    # groups — reads identically everywhere, with `^` and `$` as LINE anchors
+    # groups — reads identically everywhere, with `^` and `$` as line anchors
     # (Ruby's reading). The evidence is spec/corpus/fixtures/patterns.json.
     module PatternSubset
       Rejection = Struct.new(:construct, :reason)
@@ -57,13 +57,13 @@ module Hecks
 
       # nil when the pattern is admitted, a Rejection when it is not.
       #
-      # A CHARACTER WALK, deliberately plain : the subset is defined by this
+      # A character walk, deliberately plain : the subset is defined by this
       # walk, and a cleverer spelling would hide what it admits. An escaped
-      # construct is a LITERAL, not a violation — `\(\?=` is the three
+      # construct is a literal, not a violation — `\(\?=` is the three
       # characters "(?=" and says nothing about lookahead — which is why this
       # steps over each backslash pair rather than matching the pattern as a
       # whole.
-      # One character walk is the subset's DEFINITION (see the method
+      # One character walk is the subset's definition (see the method
       # comment above): each construct-check is a branch in a single
       # ordered pass sharing `index`/`in_class`/`class_start`. Splitting
       # the branches into separate methods would force those three cursor
@@ -72,10 +72,14 @@ module Hecks
       # methods agreeing about a shared cursor" — exactly what the walk's
       # own comment says a cleverer spelling would obscure.
       # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      #
+      # @param pattern [String, Symbol, #to_s] the declared `pattern:` regex source
+      # @return [Rejection, nil] the reason the pattern is refused, or `nil` if it is
+      #   entirely within the portable subset
       def validate(pattern)
         chars = pattern.to_s.chars
         index = 0
-        # A CHARACTER-CLASS INTERIOR IS A DIFFERENT ALPHABET : inside `[...]`,
+        # A character-class interior is a different alphabet : inside `[...]`,
         # `*`, `+`, `?`, `(`, `?` are literal characters, not quantifiers or
         # group syntax — `[*+]` means "a literal asterisk or plus". `]` is
         # only the class's close when it isn't the first character after `[`
@@ -132,7 +136,7 @@ module Hecks
         nil
       end
 
-      # SPELLED OUT, not derived from the key : these strings are the refusal
+      # Spelled out, not derived from the key : these strings are the refusal
       # a caller reads.
       CONSTRUCTS = {
         backreference:       "backreference",
@@ -145,8 +149,17 @@ module Hecks
         possessive:          "possessive quantifier"
       }.freeze
 
+      # Builds the rejection for one refused construct.
+      #
+      # @param key [Symbol] a key of `CONSTRUCTS`/`REASONS`, such as `:lookahead`
+      # @return [Rejection] the construct's name and the reason it is refused
       def refuse(key) = Rejection.new(CONSTRUCTS.fetch(key), REASONS.fetch(key))
 
+      # Says whether a POSIX bracket class (`[:digit:]` and friends) starts at `index`.
+      #
+      # @param chars [Array<String>] the pattern, split into characters
+      # @param index [Integer] the position to check
+      # @return [Boolean] whether a POSIX bracket class starts at `index`
       def posix_class_at?(chars, index)
         return false unless chars[index] == "[" && chars[index + 1] == ":"
 
@@ -156,9 +169,13 @@ module Hecks
       end
 
       # A possessive quantifier is `*+`, `++`, `?+`, or a bounded `{n}`/{n,m}`
-      # immediately followed by `+` — only checked OUTSIDE a character class,
+      # immediately followed by `+` — only checked outside a character class,
       # where `*`, `+`, `?`, `{`, `}` are quantifier syntax rather than
       # literal characters.
+      #
+      # @param chars [Array<String>] the pattern, split into characters
+      # @param index [Integer] the position to check
+      # @return [Boolean] whether a possessive quantifier starts at `index`
       def possessive_at?(chars, index)
         return true if %w[* + ?].include?(chars[index]) && chars[index + 1] == "+"
         return false unless chars[index] == "{"
@@ -169,6 +186,11 @@ module Hecks
 
       # Length of a `{n}` / `{n,}` / `{n,m}` bound starting at `index`, or nil
       # if what's there isn't one.
+      #
+      # @param chars [Array<String>] the pattern, split into characters
+      # @param index [Integer] the position the bound is expected to start at
+      # @return [Integer, nil] the bound's length in characters, or `nil` if `index`
+      #   does not start a `{n}`/`{n,}`/`{n,m}` bound
       def bounded_quantifier_length(chars, index)
         cursor = index + 1
         digit_seen = false

data/lib/hecks/bluebook/policy.rb

@@ -1,5 +1,5 @@
-# GENERATED — projected from the language's own Policy aggregate.
-# DO NOT EDIT: the holding half is rendered, and Behaviour::Policy
+# Generated — projected from the language's own Policy aggregate.
+# Do not edit: the holding half is rendered, and Behaviour::Policy
 # is where anything hand-written belongs.
 require_relative "behaviour/policy"
 
@@ -10,28 +10,30 @@ module Hecks
       include Behaviour::Policy
 
       emits_ir(
-        name:            :name,
-        on_event:        :on_event,
-        trigger_command: :trigger_command,
-        target_domain:   :target_domain,
-        where:           :where,
-        for_each:        :for_each,
-        with_spec:       -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
-        where_ast:       -> { where_ast }
+        name:               :name,
+        on_event:           :on_event,
+        trigger_command:    :trigger_command,
+        target_domain:      :target_domain,
+        expect_undelivered: :expect_undelivered,
+        where:              :where,
+        for_each:           :for_each,
+        with_spec:          -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
+        where_ast:          -> { where_ast }
       )
 
-      attr_reader :name, :on_event, :trigger_command, :target_domain, :where, :for_each, :with_spec
+      attr_reader :name, :on_event, :trigger_command, :target_domain, :expect_undelivered, :where, :for_each, :with_spec
 
-      # AGGREGATE, DECLARED AND DELIBERATELY OFF THE WIRE
+      # Aggregate, declared and deliberately off the wire
       # the wire format is a pinned contract, and it does not carry
       # where a policy was written before the builder hoisted it
       attr_accessor :aggregate
 
-      def initialize(name:, on_event: nil, trigger_command: nil, target_domain: nil, where: nil, for_each: nil, with_spec: [], aggregate: nil)
+      def initialize(name:, on_event: nil, trigger_command: nil, target_domain: nil, expect_undelivered: false, where: nil, for_each: nil, with_spec: [], aggregate: nil)
         @name = name.to_s
         @on_event = on_event
         @trigger_command = trigger_command
         @target_domain = target_domain
+        @expect_undelivered = expect_undelivered.to_s == "true"
         @where = where
         @for_each = for_each
         @with_spec = with_spec

data/lib/hecks/bluebook/process_manager.rb

@@ -3,8 +3,8 @@ require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # `compensates` — a SECOND `DispatchSpec`, shape-identical to this
-    # one, naming the command that undoes THIS dispatch specifically
+    # `compensates` — a second `DispatchSpec`, shape-identical to this
+    # one, naming the command that undoes this dispatch specifically
     # (see `ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
     # comment). `nil` for a dispatch with nothing to undo (a pure
     # bookkeeping mark, or one whose own effect is superseded by a later
@@ -14,7 +14,7 @@ module Hecks
     # used" bar would refuse a second level speculatively.
     DispatchSpec = Struct.new(:command_name, :with_spec, :compensates, keyword_init: true) do
       # A Struct already answers to_h; including the mixin puts the
-      # DECLARED emission ahead of Struct's own in the ancestry, which
+      # declared emission ahead of Struct's own in the ancestry, which
       # is what makes the shape data rather than a method body.
       include Hecks::IR
 
@@ -39,36 +39,40 @@ module Hecks
 
     # The compensation half of a procedure, as its own thing.
     #
-    # A PROCESS MANAGER coordinates: legs, states, an opinion about who goes
-    # next. A SAGA undoes: what makes the world good again when a leg it
+    # A process manager coordinates: legs, states, an opinion about who goes
+    # next. A saga undoes: what makes the world good again when a leg it
     # dispatched is refused. Two concepts, and the industry slurs them into one
     # word — so here they are two objects, and a procedure either has a saga or
     # does not.
     #
     # `undoes` is the ordered list of commands the compensation sends — a
-    # STATIC PREVIEW, declaration order (`Behaviour::ProcessManager#saga`),
+    # static preview, declaration order (`Behaviour::ProcessManager#saga`),
     # not one instance's own runtime history. Per-dispatch compensation
     # (`compensates`, on the step it compensates for) moved most of what
     # a saga undoes off this leg's own hand-written body and onto
     # whichever forward dispatch each one undoes — this reads every
-    # declared `compensates` across the WHOLE saga first, then whatever
+    # declared `compensates` across the whole saga first, then whatever
     # this leg's own hand-written body still lists, for compensation
-    # that isn't expressible as "undo command X." WHICH of a declared
+    # that isn't expressible as "undo command X." which of a declared
     # `compensates` actually fires for one instance, and in what order
     # (newest-first, completed-legs-only), is `SagaInterpreter`'s own
     # dynamic `completed_compensations` — a per-instance runtime fact
     # this declaration-only object could never hold.
     #
-    # NAMING COLLISION, ONCE FLAGGED, NOW RESOLVED — `command`'s own
+    # **Naming collision, once flagged, now resolved** — `command`'s own
     # `corrects event, reverses: true` (docs/implemented/decisions/0036-
     # corrects-is-an-appended-fact-not-a-rewrite.md) already claimed
-    # `reverses` for a different meaning: auto-deriving a command's OWN
-    # corrective mutation from a past EVENT, not a saga's own
-    # compensating leg from a past DISPATCH. This feature keeps
+    # `reverses` for a different meaning: auto-deriving a command's own
+    # corrective mutation from a past event, not a saga's own
+    # compensating leg from a past dispatch. This feature keeps
     # `reverses` reserved for `corrects` and uses `compensates` for
     # per-dispatch saga compensation instead — a deliberate choice, not
     # an accidental collision.
     Saga = Struct.new(:trigger, :from_state, :to_state, :compensations, keyword_init: true) do
+      # Lists the commands this saga sends to undo a refused leg.
+      #
+      # @return [Array<String>] the name of each compensating command, in the order
+      #   `compensations` lists them
       def undoes = compensations.map(&:command_name)
 
       def to_s = "#{trigger} → #{to_state} (#{undoes.join(', ')})"
@@ -78,10 +82,10 @@ module Hecks
     # produced by `DSL::ProcessManagerBuilder` — its start/end events,
     # correlation field, derived states, and handler rows. Its
     # compensation half (`saga`, `Behaviour::ProcessManager#saga`) is
-    # DERIVED from the handler answering `REFUSED`, below, not declared as
+    # derived from the handler answering `REFUSED`, below, not declared as
     # its own construct.
     class ProcessManager
-      # The BLUEBOOK's name for this construct, asked the same way of a class
+      # The bluebook's name for this construct, asked the same way of a class
       # that has crossed over and of an IR object that has not. Collapses into
       # Construct when this one crosses.
       # The trigger of a compensating leg. Not an event name — no aggregate
@@ -120,6 +124,15 @@ module Hecks
 
       attr_reader :name, :correlates_by, :starts_on, :ends_on, :states, :handlers
 
+      # @param name [String, Symbol] the process manager's declared name
+      # @param correlates_by [Symbol, nil] the payload field a triggering event's
+      #   instances are correlated by
+      # @param starts_on [String, nil] the event that starts a new instance
+      # @param ends_on [String, nil] the event that ends an instance
+      # @param states [Array<String>] the declared states this procedure's instances pass
+      #   through
+      # @param handlers [Array<Bluebook::ProcessManagerHandler>] the declared handler rows,
+      #   one per (event, state) leg
       def initialize(name:, correlates_by: nil, starts_on: nil, ends_on: nil,
                      states: [], handlers: [])
         @name          = name.to_s

data/lib/hecks/bluebook/project_discovery.rb

@@ -8,10 +8,15 @@ module Hecks
 
       attr_reader :root
 
+      # @param root [String] the directory to search under
       def initialize(root)
         @root = File.expand_path(root)
       end
 
+      # Walks `root` for every directory that holds `.bluebook` files.
+      #
+      # @return [Array<String>] the absolute path of each `bluebook` directory found,
+      #   sorted; a directory named in `SKIPPED_DIRECTORIES` is pruned from the walk
       def bluebook_directories
         found = []
         Find.find(root) do |path|

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)
@@ -86,15 +130,15 @@ module Hecks
         end
       end
 
-      # THE ACTUAL "more than one tenant" MOMENT — Runtime::TenantCheck's
+      # The actual "more than one tenant" moment — Runtime::TenantCheck's
       # own header names this table as the one place real multitenancy
-      # happens: the SAME on-disk directory (one domain, one
-      # `persisted_by` binding) registering a SECOND time, under a
-      # different realm, into this SAME shared route table. A directory's
-      # FIRST registration is never refused here — nothing shares its
+      # happens: the same on-disk directory (one domain, one
+      # `persisted_by` binding) registering a second time, under a
+      # different realm, into this same shared route table. A directory's
+      # first registration is never refused here — nothing shares its
       # data yet, so a plain single-tenant deployment on an ordinary
       # adapter (Postgres, no schema story) still boots exactly as
-      # before. Only the SECOND (and any later) registration of that
+      # before. Only the second (and any later) registration of that
       # same directory is refused, and refused before this call adds its
       # routes to the table — so a leaking tenant's requests never
       # become reachable through `Router#resolve` in the first place.

data/lib/hecks/bluebook/query.rb

@@ -6,16 +6,21 @@ 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.
+    # A query — an ask, declared on an aggregate or on one of its entities.
     #
-    # It crosses over as an INSTANCE rather than a class, and the reason is worth
+    # It crosses over as an instance rather than a class, and the reason is worth
     # stating because it is the boundary of the pattern. A query inherits its
     # whole body from `QuerySpecification::Common::Options` — `wheres`,
     # `order_by`, `limit`, `offset`, `cursor`,
     # `authorization`, `null_semantics`, `inspection` — and those
-    # are INSTANCE methods that the runtime and the SQLite adapter both read.
+    # are instance methods that the runtime and the SQLite adapter both read.
     # Hoisting the declaration onto a metaclass would put the identity and the
     # specification on opposite sides of the object.
     #
@@ -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,
@@ -54,11 +78,14 @@ module Hecks
         @attributes  = attributes
       end
 
-      # A query's shape is NOT fixed — `extra_options_to_h` carries
+      # A query's shape is not fixed — `extra_options_to_h` carries
       # whatever options the specification layer grew (count, median,
       # 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

@@ -4,11 +4,11 @@ module Hecks
   module Bluebook
     # A read model — an ask that gathers heads from more than one aggregate.
     #
-    # Like a query it crosses over as an INSTANCE, and for the same reason: its
+    # Like a query it crosses over as an instance, and for the same reason: its
     # body is inherited from `QuerySpecification::ReadModel::Specification`, whose
     # readers the runtime and the SQLite adapter both call on the object. It gains
     # an identity and an owner ; it keeps the name it always had, because only a
-    # CLASS ever had a competing answer for `name`.
+    # class ever had a competing answer for `name`.
     class ReadModel < QuerySpecification::ReadModel::Specification
       include Construct
 
@@ -29,11 +29,27 @@ module Hecks
       attr_reader :name, :description, :reference_name, :reference_target, :aggregate_heads, :group_by,
                   :count, :median_field
 
-      # `reference_name:`/`reference_target:` are nil for a ROOTLESS read
+      # `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, **)
@@ -47,11 +63,11 @@ module Hecks
         # `group_by_fields` is the convenience reader everything but
         # `to_h`/the Judge's own generic walk actually wants.
         @group_by         = group_by
-        # ABSENT IS NOT FALSE. `@count` stays nil rather than becoming
+        # **Absent is not false**. `@count` stays nil rather than becoming
         # `false` when undeclared — the same "if you declare it, declare
         # something" reading `Lifecycle`'s own optional fields rely on
         # (MetaValidator::Judge#setters skips a setter whose every
-        # source is `nil`, so an ALWAYS-false `@count` would dispatch
+        # source is `nil`, so an always-false `@count` would dispatch
         # `ReadModel.Count` on every read model that never wrote the
         # word at all). `!!count` collapses a truthy DSL `true` (or a
         # reconstructed `true`) to the same `true`/`nil` pair either path
@@ -60,15 +76,15 @@ module Hecks
         @median_field     = median_field&.to_sym
       end
 
-      # `.to_sym` regardless of source — the DIRECT builder path stores
+      # `.to_sym` regardless of source — the direct builder path stores
       # symbols, but `Reconstruction::Shapes#group_by_field` (the
-      # replayed-from-the-meta-domain path every REAL boot actually
+      # replayed-from-the-meta-domain path every real boot actually
       # goes through) reads the field back as a String, the same way
-      # `aggregate_heads`' own `:as` does. Row hash KEYS built by
+      # `aggregate_heads`' own `:as` does. Row hash keys built by
       # `Value.materialize_unwrapped` are symbols (`attr.name`), so
       # this has to be too, or `row[field]` in `nest` silently misses.
 
-      # `wheres`/`order_by`/`limit` are spelled explicitly here, the SAME
+      # `wheres`/`order_by`/`limit` are spelled explicitly here, the same
       # mechanism `Query#to_h` already uses (query.rb, read directly
       # before this was written) — always present, `wheres` a (possibly
       # empty) array and `order_by`/`limit` nil when undeclared, exactly
@@ -78,22 +94,26 @@ module Hecks
       # than a reader needing to learn a second one. See this file's own
       # `filtered_head_name` and language/bluebook/syntax.bluebook's
       # `ReadModel` `where`/`order_by`/`limit` member rows for the history
-      # of why this WAS narrower, and 2026-08-11's read-model where/
+      # of why this was narrower, and 2026-08-11's read-model where/
       # order_by/limit task for why it stopped being.
       # Same dynamic tail as a Query's, plus two collections whose
-      # ROWS are plain hashes rather than constructs — they are
+      # rows are plain hashes rather than constructs — they are
       # normalised here rather than by `many`, which recurses through
       # `to_h` and would have nothing to call.
-      # `count`/`median_field` are ABSENT (no key at all), not `nil`,
+      # `count`/`median_field` are absent (no key at all), not `nil`,
       # when undeclared — unlike `group_by` (always a `[]`, never
-      # missing) they are the FIRST fields this construct has ever
-      # added that no OLDER real corpus member could possibly carry, so
+      # missing) they are the first fields this construct has ever
+      # added that no older real corpus member could possibly carry, so
       # merging them unconditionally would have put a `null` onto every
       # existing read model's own wire shape (banking's
       # `ComplianceDashboard`/`CustomerPortfolio`, the language's own
       # `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