hecks 1.4.0 → 1.5.0

data/lib/hecks/projections/glossary.rb

@@ -17,25 +17,29 @@ module Hecks
     # "no, that's wrong". A banker, a support rep, the CEO and an engineer
     # read the same page.
     #
-    # **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.
+    # ## Three things follow from that audience
     #
-    # **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/).
+    # 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>)
     #   # => { "glossary.md" => "...", "html/index.html" => "..." }
@@ -59,6 +63,14 @@ module Hecks
 
       module_function
 
+      # 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 options [Hash] unused; accepted to satisfy the registry's call shape
+      # @return [Hash{String => String}] `"glossary.md"` and `"html/index.html"`,
+      #   each mapped to its rendered content
       def call(bluebook:, options: {})
         markdown = Markdown.render(document(bluebook))
         { "glossary.md" => markdown, "html/index.html" => Html.render(markdown) }
@@ -66,6 +78,11 @@ module Hecks
 
       # ── 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
+      # @return [Document] the fully assembled document, ready for `Markdown.render`
       def document(bluebook)
         sections = sections(bluebook, entries(bluebook))
         Slugs.assign!(bluebook, sections)
@@ -74,6 +91,12 @@ module Hecks
 
       # 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
       def sections(bluebook, entries)
         grouped = entries.group_by(&:section)
         list = bluebook.aggregates.sort_by { |aggregate| Naming.words(aggregate.hecks_name).downcase }.map do |aggregate|
@@ -87,10 +110,16 @@ module Hecks
         list
       end
 
-      # A HEADWORD is qualified only when it would repeat within its own
+      # 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
       def with_headwords(entries, section_name)
         entries.each { |entry| entry.headword = Naming.words(entry.name) }
         entries.group_by(&:headword).each_value do |group|
@@ -101,6 +130,14 @@ 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 }
@@ -114,6 +151,10 @@ module Hecks
       # 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
       def holders(bluebook)
         bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
       end
@@ -121,6 +162,10 @@ module Hecks
       # 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
       def holder_aggregate(bluebook)
         bluebook.aggregates.each_with_object({}) do |aggregate, map|
           map[aggregate.hecks_name] = aggregate.hecks_name
@@ -131,14 +176,29 @@ module Hecks
       # 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
       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
       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
+      # @return [Array<Entry>] one entry per entity, value object, command, query,
+      #   event, policy, saga, role, and read model
       def entries(bluebook)
         homes   = holder_aggregate(bluebook)
         raisers = event_raisers(bluebook)
@@ -156,6 +216,10 @@ 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|
@@ -167,6 +231,11 @@ module Hecks
 
       # 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
+      # @return [Array<Entry>] one `:value_object`-kind entry per aggregate-declared
+      #   value object
       def value_object_entries(bluebook)
         bluebook.aggregates.flat_map do |aggregate|
           aggregate.value_objects.map do |value_object|
@@ -176,6 +245,14 @@ 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|
@@ -190,6 +267,15 @@ 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 }
@@ -198,6 +284,11 @@ 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)),
@@ -205,6 +296,11 @@ 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
@@ -216,6 +312,9 @@ module Hecks
       # 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
       def role_entries(bluebook)
         by_role = Hash.new { |hash, key| hash[key] = [] }
         holders(bluebook).each do |holder|
@@ -228,6 +327,10 @@ module Hecks
 
       # 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
       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 })
@@ -244,8 +347,20 @@ module Hecks
       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]
         def assign!(bluebook, sections)
           seen = Hash.new(0)
           take = lambda do |text|
@@ -267,6 +382,10 @@ module Hecks
       # (a cross-domain command like `Notifications.Send`) answers nil,
       # and the sentence says it in words with no link.
       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|
@@ -275,6 +394,12 @@ 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
         def key_of(entry)
           case entry.kind
           when :command, :query, :value_object then [entry.kind, entry.within, entry.name]
@@ -282,6 +407,14 @@ module Hecks
           end
         end
 
+        # Looks up one entry or aggregate section by its key.
+        #
+        # @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
         def [](kind, name, within: nil)
           @by_key[within ? [kind, within, name] : [kind, name]]
         end
@@ -289,6 +422,15 @@ module Hecks
         # 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
         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/model/deviations.rb

@@ -80,19 +80,63 @@ module Hecks
         # 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.
+        #
+        # @param field [String, Symbol] the field name to check
+        # @return [Boolean] true if `field` is a parent pointer (`Assembly::PARENT_POINTERS`,
+        #   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.
+        #
+        # @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.
+        #
+        # @param name [String] the construct's name, an `OFF_THE_WIRE` key
+        # @return [Array<Symbol>] fields declared but deliberately not emitted for `name`;
+        #   empty if `name` has none
         def off_the_wire(name) = OFF_THE_WIRE.fetch(name, {}).keys
+
+        # Names `name`'s model-only fields.
+        #
+        # @param name [String] the construct's name, a `COMPUTED` key
+        # @return [Array<Symbol>] model-only fields computed rather than declared for
+        #   `name`; empty if `name` has none
         def computed(name)     = COMPUTED.fetch(name, {}).keys
+
+        # Names `name`'s containment edges.
+        #
+        # @param name [String] the construct's name, a `CONTAINED` key
+        # @return [Array<Symbol>] fields the model holds that the grammar declares as
+        #   containment edges instead, for `name`; empty if `name` has none
         def contained(name)    = CONTAINED.fetch(name, [])
+
+        # Names `name`'s folded fields and what each gathers.
+        #
+        # @param name [String] the construct's name, a `FOLDED` key
+        # @return [Hash{Symbol => Array<Symbol>}] each folded field for `name`, mapped to
+        #   the declared fields it gathers; empty if `name` has none
         def folded(name)       = FOLDED.fetch(name, {})
+
+        # Names `name`'s unpacked fields and what each opens into.
+        #
+        # @param name [String] the construct's name, an `UNPACKED` key
+        # @return [Hash{Symbol => Array<Symbol>}] each declared field for `name` that opens
+        #   into several model fields, mapped to those fields; empty if `name` has none
         def unpacked(name)     = UNPACKED.fetch(name, {})
+
+        # Names `name`'s dynamic-tail fields.
+        #
+        # @param name [String] the construct's name, a `DYNAMIC_TAIL` key
+        # @return [Array<Symbol>] fields for `name` emitted by `to_h`'s own merge rather
+        #   than by `emits_ir`; empty if `name` has none
         def dynamic_tail(name) = DYNAMIC_TAIL.fetch(name, [])
       end
     end

data/lib/hecks/projections/model.rb

@@ -17,7 +17,7 @@ module Hecks
     # written — the chapter looked generatable and was not, until its
     # `@hecks_root`, ports table and child stamping moved behind `settle`.
     #
-    # The HOST manifest is the honest part. The grammar states the fields;
+    # The `HOST` manifest is the honest part. The grammar states the fields;
     # it does not state which constructs are Ruby classes rather than
     # instances, what a constructor's defaults are, or how a value is
     # coerced on the way in. Those are facts about Ruby, not about
@@ -65,10 +65,26 @@ module Hecks
 
       module_function
 
+      # Renders every `HOST`-listed construct's holding half.
+      #
+      # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter itself (the language
+      #   describing its own constructs), not a domain being projected
+      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
+      #   `Projector::Target` calling convention
+      # @return [Hash{String => String}] each construct's output filename mapped to its
+      #   rendered Ruby source
       def call(bluebook:, options: {})
         HOST.to_h { |name, host| [host.fetch(:file), render(bluebook, name, host)] }
       end
 
+      # Renders one construct's class: emission, readers and constructor, wrapped in
+      # the generated-file header and namespace.
+      #
+      # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter the construct's own
+      #   attributes are read from
+      # @param name [String] the construct's name, a key into `HOST` (`"Policy"`, ...)
+      # @param host [Hash{Symbol => Object}] `name`'s `HOST` entry
+      # @return [String] the rendered class source, ready to write to `host[:file]`
       def render(bluebook, name, host)
         <<~RUBY
           # Generated — projected from the language's own #{name} aggregate.
@@ -98,6 +114,11 @@ module Hecks
       # A computed field (Deviations::COMPUTED) is emitted too — it is
       # model-only by definition, so it rides after the declared fields
       # and must have a `renders` entry, there being nothing to `send`.
+      #
+      # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter the construct's own
+      #   attributes are read from
+      # @param name [String] the construct's name, a key into `HOST`
+      # @return [String] the rendered `emits_ir(...)` call, one field per line
       def emits(bluebook, name)
         fields  = emitted_fields(bluebook, name) + Deviations.computed(name)
         renders = HOST.fetch(name).fetch(:renders, {})
@@ -110,6 +131,13 @@ module Hecks
       # deviation the tables account for. The generator and
       # spec/model_shape_conformance_spec compute this the same way, from
       # the same tables, which is the point of the tables being in lib.
+      #
+      # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter the construct's own
+      #   attributes are read from
+      # @param name [String] the construct's name, an aggregate on `bluebook`
+      # @return [Array<Symbol>] the declared attribute names, minus every field
+      #   `Deviations` marks as parent-ref, judge-only, off-the-wire, dynamic-tail,
+      #   folded, or unpacked
       def emitted_fields(bluebook, name)
         bluebook.aggregate(name).attributes.map(&:name)
                 .reject { |f| Deviations.parent_ref?(f) } -
@@ -120,6 +148,11 @@ module Hecks
           Deviations.unpacked(name).keys
       end
 
+      # Renders the `attr_reader` line for every emitted field, plus an `attr_accessor`
+      # for each field the model deliberately keeps off the wire.
+      #
+      # @param host [Hash{Symbol => Object}] the construct's `HOST` entry
+      # @return [String] the rendered reader/accessor lines, one construct's worth
       def readers(host)
         lines = ["attr_reader #{host.fetch(:readers).map { |r| ":#{r}" }.join(', ')}"]
         accessors = host.fetch(:accessors, [])
@@ -137,6 +170,11 @@ module Hecks
         end).join("\n")
       end
 
+      # Renders the `initialize` that assigns every declared field, coerced as `HOST`
+      # states, and calls `settle` unless the construct opts out.
+      #
+      # @param host [Hash{Symbol => Object}] the construct's `HOST` entry
+      # @return [String] the rendered `def initialize ... end` block
       def constructor(host)
         args = host.fetch(:defaults).map { |f, d| d ? "#{f}: #{d}" : "#{f}:" }.join(", ")
         body = host.fetch(:defaults).keys.map do |f|
@@ -147,7 +185,19 @@ module Hecks
         "def initialize(#{args})\n#{body.join("\n")}\nend"
       end
 
+      # Indents every non-blank line of a rendered block, for nesting it inside the
+      # class body.
+      #
+      # @param text [String] the block to indent
+      # @param by [Integer] how many spaces to prefix each non-blank line with
+      # @return [String] the indented text
       def indent(text, by) = text.lines.map { |l| l.strip.empty? ? l : (" " * by) + l }.join
+
+      # Wraps prose into `# `-prefixed comment lines, for a reader-declared reason
+      # rendered back into the generated file.
+      #
+      # @param text [String] the prose to wrap
+      # @return [String] the wrapped text, its lines joined by `"\n# "`
       def wrap(text) = text.scan(/.{1,62}(?:\s|$)/).map(&:strip).join("\n# ")
     end
   end

data/lib/hecks/projections/oidc.rb

@@ -7,7 +7,8 @@ module Hecks
     # an identity provider has to know about this domain before it can
     # issue a token that means anything here.
     #
-    # The artifact half of something already half-built.
+    # ## The artifact half of something already half-built
+    #
     # `spec/oidc_projection_spec.rb` covers the integration half — verified
     # claims in, `IdentityResolution.resolve` → `Authorization.holds_role?`
     # → a dispatch scoped by `Hecks.as_caller(role:)`. That half enforces
@@ -24,8 +25,9 @@ module Hecks
     # `Ports::Authorization.holds_role?` compares against a real
     # `Governance::RoleAssignment`.
     #
-    # Roles come from the commands, not from governance. A command's own
-    # `role "Compliance officer"` is in the bluebook IR
+    # ## Roles come from the commands, not from governance
+    #
+    # A command's own `role "Compliance officer"` is in the bluebook IR
     # (`Command#role`), whereas `uses_framework "Governance"` is
     # declared in the `.hecksagon` — which `call(bluebook:, options:)`
     # cannot see at all. Reading the commands is both the only thing
@@ -47,6 +49,13 @@ module Hecks
       # `audience:` overrides the domain name, for the ordinary case
       # where the IdP's registered audience is a URL rather than a bare
       # chapter name.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter being projected
+      # @param options [Hash{Symbol => Object}] `:audience` (String, Symbol, nil)
+      #   overrides the manifest's `"audience"` value
+      # @return [Hash{String => Object}] `"audience"` (String), `"scopes"` (see
+      #   `scopes_for`) and `"roles"` (`Array<String>`, every distinct declared role,
+      #   sorted)
       def call(bluebook:, options: {})
         scopes = scopes_for(bluebook)
 
@@ -67,11 +76,22 @@ module Hecks
       # through `Dispatcher#dispatch`'s dotted `Entity.Command` routing
       # is real and callable, so a manifest that never names it can
       # never grant a client a scope for it either.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter being projected
+      # @return [Array<Hash{String => Object}>] every command's scope entry (see
+      #   `command_scopes`), sorted by `"scope"`
       def scopes_for(bluebook)
         bluebook.aggregates.flat_map { |aggregate| aggregate_scopes(bluebook, aggregate) }
                 .sort_by { |scope| scope["scope"] }
       end
 
+      # Projects one aggregate's own commands and every entity nested inside it.
+      #
+      # @param bluebook [Bluebook::Chapter] the aggregate's owning chapter, for the
+      #   verb and scope prefixes
+      # @param aggregate [Bluebook::Aggregate] the aggregate being projected
+      # @return [Array<Hash{String => Object}>] the aggregate's and its entities'
+      #   scope entries (see `command_scopes`)
       def aggregate_scopes(bluebook, aggregate)
         verb_prefix  = "#{bluebook.name}::#{aggregate.hecks_name}"
         scope_prefix = "#{Naming.snake(bluebook.name)}:#{Naming.snake(aggregate.hecks_name)}"
@@ -84,6 +104,14 @@ module Hecks
       # inside `Handler`), so this recurses the same way `Chapter#verbs`
       # now does. The verb and scope prefixes grow in lockstep, each
       # `.`-joined the same way its own kind already was.
+      #
+      # @param entity [Bluebook::Entity] the entity being projected
+      # @param verb_prefix [String] the enclosing aggregate or entity's own verb
+      #   prefix, extended with this entity's name
+      # @param scope_prefix [String] the enclosing aggregate or entity's own scope
+      #   prefix, extended with this entity's snake-cased name
+      # @return [Array<Hash{String => Object}>] this entity's and its nested entities'
+      #   scope entries (see `command_scopes`)
       def entity_scopes(entity, verb_prefix, scope_prefix)
         verb_prefix  = "#{verb_prefix}.#{entity.hecks_name}"
         scope_prefix = "#{scope_prefix}.#{Naming.snake(entity.hecks_name)}"
@@ -96,6 +124,15 @@ module Hecks
       # spelled in, and snake_cased through the same `Naming.snake` the
       # facade uses to name a command's own door method, so a scope and
       # the Ruby call that satisfies it cannot drift apart.
+      #
+      # @param commands [Array<Bluebook::Command>] the commands to project
+      # @param verb_prefix [String] the owning aggregate or entity's fully-qualified
+      #   verb prefix
+      # @param scope_prefix [String] the owning aggregate or entity's snake-cased
+      #   scope prefix
+      # @return [Array<Hash{String => Object}>] one entry per command: `"scope"`
+      #   (String), `"verb"` (String), `"role"` (String, `nil` if the command
+      #   declares none)
       def command_scopes(commands, verb_prefix, scope_prefix)
         commands.map do |command|
           {