hecks 2.8.0 → 3.0.0

data/lib/hecks/projections/glossary.rb

@@ -10,100 +10,46 @@ require_relative "glossary/html"
 
 module Hecks
   module Projections
-    # A chapter, projected as its ubiquitous language — a glossary for the
-    # whole team, in the sense Evans meant (DDD ch. 2): one language,
-    # shared by domain experts and developers, written the same way in
-    # conversation, diagrams, documents and code, so that a subject-matter
-    # expert can read the model and say "yes, that's how it works" or
-    # "no, that's wrong". A banker, a support rep, the CEO and an engineer
-    # read the same page.
+    # A chapter projected as a plain-language glossary, grouped by aggregate,
+    # as `glossary.md` plus an HTML page rendered from that same Markdown.
     #
-    # ## Three things follow from that audience
-    #
-    # First, no type jargon: a term is a term, not "an Aggregate" or "a
-    # Value Object", and every identifier is spelled as a person says it
-    # (`Naming.words`: `ATMCard` is "ATM card"). Second, nothing invented:
-    # every sentence is either the domain author's own words (a
-    # `description`, a `goal`, an invariant) or built mechanically from a
-    # declared fact ("Recorded after Freeze account") — the same
-    # discipline `DocsProjector` holds to; a wrong sentence is worse than
-    # a missing one. Third, grouped under the aggregate each term belongs
-    # to, A to Z within it — a reader thinks "what does Account mean"
-    # before "what starts with A", and once there reads the way a
-    # dictionary reads.
-    #
-    # ## Two files from one source
-    #
-    # `glossary.md` is the document — every construct in it renders on
-    # GitHub as-is (headings, blockquotes, ```mermaid fences, lists,
-    # in-page links). `html/index.html` is that exact Markdown string
-    # rendered into a page with a navigation rail; it is built from the
-    # Markdown, not beside it, so the two cannot drift. `bin/project_glossary`
-    # writes both to `<domain>/glossary/` beside the bluebook (examples/banking,
-    # examples/pizzas, and the QA ledger in qa/).
-    #
-    #   Projector.call(:glossary, bluebook: <the Bluebook chapter>)
+    #   Projector.call(:glossary, bluebook: chapter)
     #   # => { "glossary.md" => "...", "html/index.html" => "..." }
     module Glossary
       extend Projector::Target
 
       projects_as :glossary, emits: :files
 
-      # One term. `kind` is a Symbol the renderers never print; `facts`
-      # carries the declaration objects the sentence is built from;
-      # `headword` and `slug` are assigned once the document's order is
-      # known (a headword may need qualifying, a slug depends on what
-      # came before it).
+      # One term. `headword` and `slug` are assigned once the document's order is known.
       Entry = Struct.new(:name, :kind, :within, :section, :facts, :headword, :slug, keyword_init: true)
 
-      # One `##` of the document: an aggregate (with its own object, for
-      # the lede and diagrams) or one of the three trailing groups.
       Section = Struct.new(:name, :title, :aggregate, :terms, :slug, keyword_init: true)
 
       Document = Struct.new(:bluebook, :sections, :index, :markings, keyword_init: true)
 
       module_function
 
-      # Projects `bluebook`'s glossary as a Markdown document and the HTML
-      # page built from it.
+      # Projects `bluebook`'s glossary as a Markdown document and the HTML page built from it.
       #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to render a
-      #   glossary for
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to render
       # @param options [Hash] the registry's call shape
-      # @option options [Array<Hash{Symbol => String}>] :markings the sensitive fields a
-      #   deployment declares (`registry.pending_privacy_markings`' own shape); each
-      #   marked field is tagged with its category, and every marking is listed under
-      #   its aggregate. Absent, the glossary says nothing about sensitivity.
-      # @return [Hash{String => String}] `"glossary.md"` and `"html/index.html"`,
-      #   each mapped to its rendered content
+      # @option options [Array<Hash{Symbol => String}>] :markings sensitive fields to tag
+      #   with their category and list under their aggregate
+      # @return [Hash{String => String}] `"glossary.md"` and `"html/index.html"`
       def call(bluebook:, options: {})
         markdown = Markdown.render(document(bluebook, Array(options[:markings])))
         { "glossary.md" => markdown, "html/index.html" => Html.render(markdown) }
       end
 
-      # ── the document ─────────────────────────────────────────────────
-
       # Gathers every term, groups it into sections, assigns headings and
       # slugs, and builds the index links resolve through.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to render
-      # @param markings [Array<Hash{Symbol => String}>] the sensitive fields declared for
-      #   the chapter's aggregates; empty when none are
-      # @return [Document] the fully assembled document, ready for `Markdown.render`
       def document(bluebook, markings = [])
         sections = sections(bluebook, entries(bluebook, markings))
         Slugs.assign!(bluebook, sections)
         Document.new(bluebook: bluebook, sections: sections, index: Index.new(sections), markings: markings)
       end
 
-      # Aggregates first, a to Z by their spoken name ("Account" before
-      # "ATM card"), then the three groups nothing homes to one aggregate.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
-      #   aggregates to group by
-      # @param entries [Array<Entry>] every gathered term
-      # @return [Array<Section>] one section per aggregate, sorted, followed by
-      #   any of the Roles/Read models/Reactions sections that have entries
+      # Aggregates first, A to Z by spoken name, then the groups no aggregate homes.
       def sections(bluebook, entries)
         grouped = entries.group_by(&:section)
         list = bluebook.aggregates.sort_by { |aggregate| Naming.words(aggregate.hecks_name).downcase }.map do |aggregate|
@@ -117,16 +63,7 @@ module Hecks
         list
       end
 
-      # A headword is qualified only when it would repeat within its own
-      # section — "Open" the action and "Open (the list)" the question;
-      # "Return (key issuance)" beside another Return — never numbered
-      # (Chicago 18.9, MDN's disambiguation pages: qualify the headword).
-      #
-      # @param entries [Array<Entry>] the section's own entries
-      # @param section_name [String] the entries' own section name, for telling
-      #   an entry's own section apart from a borrowed one when qualifying
-      # @return [Array<Entry>] `entries`, headword-assigned, sorted by headword
-      #   then kind
+      # A headword is qualified only when it would repeat within its section, never numbered.
       def with_headwords(entries, section_name)
         entries.each { |entry| entry.headword = Naming.words(entry.name) }
         entries.group_by(&:headword).each_value do |group|
@@ -137,14 +74,6 @@ module Hecks
         entries.sort_by { |entry| [entry.headword.downcase, entry.kind.to_s] }
       end
 
-      # Disambiguates one entry's headword from the rest of its group.
-      #
-      # @param entry [Entry] the entry to qualify
-      # @param group [Array<Entry>] every entry sharing `entry`'s plain headword
-      # @param section_name [String] the section `entry` and `group` are being
-      #   rendered under
-      # @return [String] `entry`'s headword, qualified with "(the list)" or its
-      #   own holder's name when needed to tell it apart from the rest of `group`
       def qualified(entry, group, section_name)
         base = Naming.words(entry.name)
         return "#{base} (the list)" if entry.kind == :query && group.any? { |other| other.kind == :command }
@@ -153,26 +82,12 @@ module Hecks
         base
       end
 
-      # ── gathering ────────────────────────────────────────────────────
-
-      # An entity can carry its own commands and queries too — walked the
-      # same one level down `DocsProjector` and `Projections::Diagrams`
-      # already walk it.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to walk
-      # @return [Array<Bluebook::Aggregate, Bluebook::Entity>] every aggregate, each
-      #   immediately followed by its own nested entities
+      # Entities carry their own commands and queries, so they are walked one level down.
       def holders(bluebook)
         bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
       end
 
-      # Every holder's own aggregate, one hop or zero — an aggregate maps
-      # to itself, an entity to whichever aggregate declared it. The one
-      # fact the grouping is built on.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to walk
-      # @return [Hash{String => String}] every aggregate and entity name, mapped to
-      #   its own owning aggregate's name
+      # Maps every holder name to its owning aggregate's name.
       def holder_aggregate(bluebook)
         bluebook.aggregates.each_with_object({}) do |aggregate, map|
           map[aggregate.hecks_name] = aggregate.hecks_name
@@ -180,34 +95,18 @@ module Hecks
         end
       end
 
-      # Every event's raisers — an event is never declared, only emitted,
-      # so its home is whichever aggregate the first command that raises
-      # it belongs to; a policy or saga reacting to it inherits that home.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to walk
-      # @return [Hash{String => Array<Array(Bluebook::Aggregate, Bluebook::Command)>}]
-      #   every emitted event name, mapped to `[holder, command]` pairs for every
-      #   command that raises it; a name absent from the Hash raises nothing
+      # Maps each emitted event to its `[holder, command]` raisers. An event is never
+      # declared, so its home is the first raiser's aggregate.
       def event_raisers(bluebook)
         holders(bluebook).each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |holder, map|
           holder.commands.each { |command| command.emits.each { |event| map[event] << [holder, command] } }
         end
       end
 
-      # Strips a dotted name down to its last segment.
-      #
-      # @param qualified [String, Symbol] a dotted or bare name, such as
-      #   `"Handler.Dispatch"` or `"Freeze"`
-      # @return [String] the name after the last `.`, or the whole name if it has none
+      # The last segment of a dotted name.
       def bare(qualified) = qualified.to_s.split(".").last
 
       # Gathers every term the glossary carries, ungrouped and unordered.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather terms from
-      # @param markings [Array<Hash{Symbol => String}>] the sensitive fields declared for
-      #   the chapter's aggregates
-      # @return [Array<Entry>] one entry per entity, value object, command, query,
-      #   event, policy, saga, role, and read model
       def entries(bluebook, markings = [])
         homes   = holder_aggregate(bluebook)
         raisers = event_raisers(bluebook)
@@ -225,10 +124,6 @@ module Hecks
         entries
       end
 
-      # Gathers one entry per entity.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather entities from
-      # @return [Array<Entry>] one `:entity`-kind entry per entity
       def entity_entries(bluebook)
         bluebook.aggregates.flat_map do |aggregate|
           aggregate.entities.map do |entity|
@@ -238,15 +133,7 @@ module Hecks
         end
       end
 
-      # Aggregates only — an entity declares no value objects of its own
-      # (`Bluebook::Entity` deliberately does not answer `value_objects`).
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather value
-      #   objects from
-      # @param markings [Array<Hash{Symbol => String}>] the sensitive fields declared for
-      #   the chapter's aggregates, each carried onto the value object it reaches into
-      # @return [Array<Entry>] one `:value_object`-kind entry per aggregate-declared
-      #   value object
+      # Aggregates only; `Bluebook::Entity` deliberately does not answer `value_objects`.
       def value_object_entries(bluebook, markings = [])
         bluebook.aggregates.flat_map do |aggregate|
           marked = Sensitivity.for_aggregate(markings, bluebook.name, aggregate)
@@ -259,14 +146,6 @@ module Hecks
         end
       end
 
-      # Gathers one entry per command and query.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather commands
-      #   and queries from
-      # @param homes [Hash{String => String}] every holder's name, mapped to its
-      #   owning aggregate's name (as `holder_aggregate` builds)
-      # @return [Array<Entry>] one `:command`-kind or `:query`-kind entry per command
-      #   and query, commands first
       def verb_entries(bluebook, homes)
         holders(bluebook).flat_map do |holder|
           commands = holder.commands.map do |command|
@@ -281,15 +160,6 @@ module Hecks
         end
       end
 
-      # Gathers one entry per raised event.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
-      #   policies checked for reactions
-      # @param raisers [Hash{String => Array<Array(Bluebook::Aggregate, Bluebook::Command)>}]
-      #   every event name, mapped to its raising `[holder, command]` pairs (as
-      #   `event_raisers` builds)
-      # @param home_of [Proc, #call] answers an event name's owning aggregate name, or nil
-      # @return [Array<Entry>] one `:event`-kind entry per raised event
       def event_entries(bluebook, raisers, home_of)
         raisers.map do |event, raised_by|
           reactions = bluebook.policies.select { |policy| bare(policy.on_event) == event }
@@ -298,11 +168,6 @@ module Hecks
         end
       end
 
-      # Gathers one entry per declared policy.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather policies from
-      # @param home_of [Proc, #call] answers an event name's owning aggregate name, or nil
-      # @return [Array<Entry>] one `:policy`-kind entry per declared policy
       def policy_entries(bluebook, home_of)
         bluebook.policies.map do |policy|
           Entry.new(name: policy.name, kind: :policy, section: home_of.call(bare(policy.on_event)),
@@ -310,11 +175,6 @@ module Hecks
         end
       end
 
-      # Gathers one entry per declared process manager.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather sagas from
-      # @param home_of [Proc, #call] answers an event name's owning aggregate name, or nil
-      # @return [Array<Entry>] one `:saga`-kind entry per declared process manager
       def saga_entries(bluebook, home_of)
         bluebook.process_managers.map do |saga|
           shape = saga.to_h
@@ -323,12 +183,7 @@ module Hecks
         end
       end
 
-      # Cross-cutting by nature — `System` and `Customer` issue commands
-      # across half the aggregates here — so a role belongs to no single
-      # one and gets its own section.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather roles from
-      # @return [Array<Entry>] one `:role`-kind entry per distinct role named by a command
+      # Roles cut across aggregates, so they get their own section.
       def role_entries(bluebook)
         by_role = Hash.new { |hash, key| hash[key] = [] }
         holders(bluebook).each do |holder|
@@ -339,42 +194,21 @@ module Hecks
         end
       end
 
-      # A read model joins heads from more than one aggregate — its own
-      # header says so — so it belongs to none of them.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to gather read
-      #   models from
-      # @return [Array<Entry>] one `:read_model`-kind entry per declared read model
+      # A read model joins heads from more than one aggregate, so it belongs to none.
       def read_model_entries(bluebook)
         bluebook.read_models.map do |read_model|
           Entry.new(name: read_model.name, kind: :read_model, section: READ_MODELS, facts: { read_model: read_model })
         end
       end
 
-      # ── anchors ──────────────────────────────────────────────────────
-
-      # **GitHub's own heading slugs, reproduced** — lowercase, punctuation
-      # dropped, spaces to hyphens, a repeat gets "-1", "-2" in document
-      # order. Computed here, once, in the order the headings will appear,
-      # so a link written into the Markdown lands on the same heading
-      # whether GitHub renders the `.md` or `Html` renders the page.
+      # Reproduces GitHub's heading slugs, computed in document order, so links land the
+      # same whether GitHub renders the `.md` or `Html` renders the page.
       module Slugs
         module_function
 
-        # Reproduces GitHub's own heading-to-slug transform.
-        #
-        # @param text [String] the heading text to slugify
-        # @return [String] `text` lowercased, stripped of punctuation, spaces turned
-        #   to hyphens
         def github(text) = text.to_s.downcase.gsub(/[^\p{Word}\- ]/, "").tr(" ", "-")
 
-        # Assigns every section's and every entry's own slug, in document order.
-        #
-        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter the document
-        #   titles itself after
-        # @param sections [Array<Section>] the sections to assign slugs to, in the
-        #   order they render
-        # @return [void]
+        # Assigns every section's and entry's slug, in document order.
         def assign!(bluebook, sections)
           seen = Hash.new(0)
           take = lambda do |text|
@@ -390,16 +224,9 @@ module Hecks
         end
       end
 
-      # **Where a declared reference points** — keyed structurally (a command
-      # by its holder and name, an event by its bare name), never by
-      # searching prose for a matching word. Anything not declared here
-      # (a cross-domain command like `Notifications.Send`) answers nil,
-      # and the sentence says it in words with no link.
+      # Resolves declared references structurally, never by searching prose. An
+      # undeclared target (a cross-domain command) answers nil and renders unlinked.
       class Index
-        # Builds the lookup table every `link` call resolves through.
-        #
-        # @param sections [Array<Section>] the document's own sections, already
-        #   built and slugged
         def initialize(sections)
           @by_key = {}
           sections.each do |section|
@@ -408,12 +235,8 @@ module Hecks
           end
         end
 
-        # Builds one entry's lookup key.
-        #
-        # @param entry [Entry] the entry to key
-        # @return [Array(Symbol, String, String), Array(Symbol, String)] `[kind, within,
-        #   name]` for a command, query, or value object (which can share a bare name
-        #   across holders); `[kind, name]` otherwise
+        # Commands, queries and value objects can share a bare name across holders, so
+        # their key includes the holder.
         def key_of(entry)
           case entry.kind
           when :command, :query, :value_object then [entry.kind, entry.within, entry.name]
@@ -421,30 +244,15 @@ module Hecks
           end
         end
 
-        # Looks up one entry or aggregate section by its key.
+        # Looks up a term or aggregate section by kind and name.
         #
-        # @param kind [Symbol] the entry's kind, or `:aggregate` for a section
-        # @param name [String] the entry's or aggregate's name
-        # @param within [String, nil] the holder's name, for a command, query, or
-        #   value object; nil otherwise
-        # @return [Entry, Section, nil] the matching entry or aggregate section, or
-        #   nil if the chapter declares none
+        # @return [Entry, Section, nil]
         def [](kind, name, within: nil)
           @by_key[within ? [kind, within, name] : [kind, name]]
         end
 
-        # A Markdown link to a term's own heading, or the plain words when
-        # the chapter declares no such term. `label:` overrides the link
-        # text for a sentence that has to tell two same-named terms apart.
-        #
-        # @param kind [Symbol] the target's kind, or `:aggregate` for a section
-        # @param name [String] the target's or aggregate's name
-        # @param within [String, nil] the holder's name, for a command, query, or
-        #   value object; nil otherwise
-        # @param label [String, nil] link text to use instead of the target's own
-        #   headword or title
-        # @return [String] a `[text](#slug)` Markdown link, or the plain words when
-        #   the chapter declares no such term
+        # A Markdown link to a term's heading, or the plain words when undeclared.
+        # `label:` overrides the link text to tell two same-named terms apart.
         def link(kind, name, within: nil, label: nil)
           target = self[kind, name, within: within]
           return label || Naming.words(name) unless target

data/lib/hecks/projections/ir.rb

@@ -1,17 +1,10 @@
 require_relative "../projector"
 
 module Hecks
-  # Reopened from projections.rb (see there for the namespace's full
-  # rationale) to define and register the :ir target below.
+  # The projection targets, each registered under a name; this file adds the `:ir` target.
   module Projections
-    # The canonical IR, as a constant. The implementation already existed
-    # and is already golden-tested (`Projector::IRProjector`, registered
-    # as `:ir`) — this only gives it the constant spelling every other
-    # target has, by re-registering the same module under the same key.
-    #
-    # Deliberately not a new implementation: two things named `IR` that
-    # each rendered IR their own way is exactly the drift this namespace
-    # exists to avoid.
+    # The canonical IR projection, registered as `:ir`.
+    # Aliases `Projector::IRProjector` rather than reimplementing it, so IR has one renderer.
     IR = Projector::IRProjector
 
     IR.extend(Projector::Target)

data/lib/hecks/projections/model/deviations.rb

@@ -1,48 +1,33 @@
 module Hecks
   module Projections
     module Model
-      # How the model's shape differs from the language's, and why.
-      #
-      # Every construct's `emits_ir` restates what the grammar declares —
-      # and the two legitimately differ, in seven ways. These lived only
-      # as prose in Ruby comments until spec/model_shape_conformance_spec
-      # made them checkable; they live here so the generator and the gate
-      # read one source rather than two that must agree.
-      #
-      # A reason is carried beside each entry because the generated file
-      # will carry it: a deviation is exactly the kind of thing whose
-      # explanation must survive regeneration, and the only way it can is
-      # to be emitted rather than typed into the output.
+      # How the model's shape legitimately differs from the language's, and why.
+      # The generator and spec/model_shape_conformance_spec read these tables.
       module Deviations
-        # What the model holds that the grammar declares elsewhere: the
-        # containment edges, stated in syntax.bluebook's Keyword rows as
-        # `context` -> `opens`.
+        # Fields the model holds that the grammar declares as containment edges
+        # (syntax.bluebook's Keyword rows, `context` -> `opens`).
         CONTAINED = {
           "Bluebook"       => %i[aggregates read_models policies process_managers],
           "Aggregate"      => %i[commands entities queries value_objects],
-          # S17, ADR 0026 — an entity may nest further entities now
-          # (`Dispatch`, inside `Handler`) — same containment edge as
-          # Aggregate's own `entities`, one level down.
+          # An entity may nest further entities (`Dispatch` inside `Handler`) (ADR 0026).
           "Entity"         => %i[commands entities queries],
           "ValueObject"    => %i[members],
           "ProcessManager" => %i[handlers]
         }.freeze
 
-        # One model field gathered from several declared ones —
-        # contracts.rb's own `[:folded, ...]` shape, as the pair it is.
+        # One model field gathered from several declared ones.
         FOLDED = {
           "Aggregate" => { lifecycle: %i[state_field state_start transitions] },
           "Entity"    => { lifecycle: %i[state_field state_start transitions] },
           "Query"     => { order_by: %i[order_field order_way] }
         }.freeze
 
-        # The inverse of a fold, and it had no name at all: one declared
-        # field opening into several the model holds apart.
+        # The inverse of a fold: one declared field opening into several model fields.
         UNPACKED = {
           "ReadModel" => { options: %i[wheres order_by limit] }
         }.freeze
 
-        # Model-only, each for its own reason rather than by oversight.
+        # Model-only fields, each with its reason.
         COMPUTED = {
           "Bluebook"    => { ir_version:     "the EMISSION's own version, not the domain's",
                              canonical_form: "the normalisation table every reader needs beside the IR" },
@@ -51,9 +36,7 @@ module Hecks
           "Policy"      => { where_ast:      "the structured form of `where`, derived from the same text at emission" }
         }.freeze
 
-        # **Declared, and deliberately not emitted**. The category that had no
-        # home anywhere before — each of these was a comment and nothing
-        # more.
+        # Declared but deliberately not emitted, each with its reason.
         OFF_THE_WIRE = {
           "Policy"      => { aggregate: "the wire format is a pinned contract, and it does not carry " \
                                         "where a policy was written before the builder hoisted it" },
@@ -62,24 +45,16 @@ module Hecks
           "ValueObject" => { rows: "the language's name for a closed set's members; emitted as `members`" }
         }.freeze
 
-        # Emitted by `to_h`'s own merge rather than by `emits_ir` — the
-        # two constructs whose shape is genuinely not fixed, because the
-        # query specification layer grew options after them.
+        # Fields emitted by `to_h`'s own merge rather than `emits_ir`, for constructs
+        # whose shape is not fixed.
         DYNAMIC_TAIL = {
-          "Query"     => %i[options],
-          "ReadModel" => %i[options group_by aggregate_heads count median_field]
+          "Query"     => %i[options returns],
+          "ReadModel" => %i[options group_by aggregate_heads count median_field sum_field avg_field
+                            min_field max_field percentile_field percentile_at any_field all_field]
         }.freeze
 
         module_function
 
-        # The grammar is relational — a Command points up at its
-        # Aggregate — where the model composes. An explicit `as:` still
-        # keeps its `_id` (Command's own `entity_id`, kept as data); the
-        # parent link itself mints bare now (ADR 0025) — `aggregate` or
-        # `bluebook`, whichever this category's creating command declares
-        # first. Entity spells its own (separate, non-colliding) text twin
-        # of the parent link `owner`. Not restated here: the one list is
-        # `Assembly::PARENT_POINTERS`, which the assembly gate reads too.
         # Tells whether `field` is a parent pointer, minted bare rather than
         # declared like an ordinary field.
         #
@@ -88,16 +63,14 @@ module Hecks
         #   or any name ending `_id`)
         def parent_ref?(field) = Hecks::Bluebook::Assembly.parent_pointer?(field)
 
-        # The judge's own fields, never the model's — read off the
-        # category's contract (`derived: { position: :walk }`), not restated.
+        # The judge's own fields, read off the category's contract (`derived: {...: :walk}`).
         #
         # @param name [String] the construct's name, an `Assembly::CONTRACTS` key
         # @return [Array<Symbol>] fields the assembly judge derives by walking, for this construct
         # @raise [KeyError] if `name` has no assembly contract
         def judge_only(name) = Hecks::Bluebook::Assembly.contract(name).walked
 
-        # The tables that carry a reason answer with names only when the
-        # caller wants the set rather than the explanations.
+        # The names in `OFF_THE_WIRE`, without the reasons.
         #
         # @param name [String] the construct's name, an `OFF_THE_WIRE` key
         # @return [Array<Symbol>] fields declared but deliberately not emitted for `name`;