hecks 1.4.0 → 1.5.1

data/lib/hecks/projector/narrate_projector.rb

@@ -5,16 +5,18 @@ module Hecks
   module Projector
     # A bluebook, projected as prose an SME can read back and confirm.
     #
-    # **What this is for**. `DocsProjector` already answers "what can I call and
-    # what does it want" for the person implementing against a domain —
-    # tables of arguments, shapes, refusal reasons. That is the wrong
-    # register for the person who can actually say whether the domain is
-    # right: the subject-matter expert who knows what an account is and has
-    # never read a markdown table in their life. This projects the same IR
-    # as sentences instead — "Debit — take money out. Issued by a Teller. It
-    # only goes through if the balance covers it." — so a domain can be
-    # read back to the person who can validate it without them learning the
-    # DSL first.
+    # ## What this is for
+    #
+    # `DocsProjector` already answers "what can I call and what does it
+    # want" for the person implementing against a domain — tables of
+    # arguments, shapes, refusal reasons. That is the wrong register for
+    # the person who can actually say whether the domain is right: the
+    # subject-matter expert who knows what an account is and has never
+    # read a markdown table in their life. This projects the same IR as
+    # sentences instead — "Debit — take money out. Issued by a Teller.
+    # It only goes through if the balance covers it." — so a domain can
+    # be read back to the person who can validate it without them
+    # learning the DSL first.
     #
     # Same source, same guarantee `DocsProjector` gives: nothing here is
     # invented. Every sentence quotes a `description`, `goal`, or `given`
@@ -24,17 +26,30 @@ module Hecks
     # (`Projector.call(:narrate, bluebook: ...)`), same aggregate-scoping
     # via `options[:aggregate]`.
     #
-    # **What it does not do**: replace `DocsProjector`. A shape table still says
-    # "id of a Customer" more precisely than any sentence would, and an
-    # implementer still wants that. This is the other document the same IR
-    # is owed — one written for the reader who is being asked "is this
-    # right?", not "how do I call it?"
+    # ## What it does not do
+    #
+    # Replace `DocsProjector`. A shape table still says "id of a
+    # Customer" more precisely than any sentence would, and an
+    # implementer still wants that. This is the other document the same
+    # IR is owed — one written for the reader who is being asked "is
+    # this right?", not "how do I call it?"
     module NarrateProjector
       module_function
 
+      # Projects `bluebook` as prose an SME can read back and confirm.
+      #
       # `options[:heading]` sets the top heading level, exactly as
       # `DocsProjector` does — so this, too, can be spliced into a larger
       # document rather than always starting at H1.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to narrate
+      # @param options [Hash] optional inputs
+      # @option options [Integer, String] :heading the top heading level; defaults to 1
+      # @option options [String, Symbol, nil] :aggregate narrows the narrative to one
+      #   aggregate, omitting the chapter intro and reactions sections
+      # @return [String] the narrative, as Markdown prose, ending in a newline
+      # @raise [Runtime::NotFound] if `options[:aggregate]` names no aggregate `bluebook`
+      #   declares
       def call(bluebook:, options: {})
         depth = (options[:heading] || 1).to_i
         only  = options[:aggregate]
@@ -50,6 +65,12 @@ module Hecks
 
       # ── the chapter ───────────────────────────────────────────────────
 
+      # Narrates the chapter-level intro: its vision, classification, former
+      # name, and the aggregates it's told through.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to narrate
+      # @param depth [Integer] the heading level for the chapter's own title
+      # @return [String] the intro's Markdown prose
       def chapter_intro(bluebook, depth)
         parts = [DocsProjector.h(depth, bluebook.name)]
         parts << bluebook.vision if bluebook.vision
@@ -66,6 +87,12 @@ module Hecks
 
       # ── one aggregate ─────────────────────────────────────────────────
 
+      # Narrates one aggregate: its description, identity, references,
+      # lifecycle, commands, queries, and nested entities.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate to narrate
+      # @param depth [Integer] the heading level for the aggregate's own title
+      # @return [String] the aggregate's Markdown prose
       def aggregate_narrative(aggregate, depth)
         parts = [DocsProjector.h(depth, aggregate.hecks_name)]
         parts << aggregate.description if aggregate.description
@@ -86,12 +113,23 @@ module Hecks
         parts.compact.join("\n\n")
       end
 
+      # Names how a holder is identified.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to describe
+      # @return [String, nil] a sentence naming `holder`'s identity fields, or nil if
+      #   it declares none
       def identity_sentence(holder)
         return nil if holder.identity_heads.empty?
 
         "Every #{holder.hecks_name} is identified by its #{to_sentence_list(holder.identity_heads.map { |h| "`#{h}`" })}."
       end
 
+      # Narrates one entity nested under `aggregate`.
+      #
+      # @param aggregate [Bluebook::Aggregate] the entity's own owning aggregate
+      # @param entity [Bluebook::Entity] the entity to narrate
+      # @param depth [Integer] the heading level for the entity's own title
+      # @return [String] the entity's Markdown prose
       def entity_narrative(aggregate, entity, depth)
         parts = [DocsProjector.h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})")]
         parts << entity.description if entity.description
@@ -106,6 +144,11 @@ module Hecks
 
       # ── the machine ───────────────────────────────────────────────────
 
+      # Narrates a holder's own lifecycle transitions.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to describe
+      # @return [String, nil] a sentence per lifecycle transition, or nil if `holder`
+      #   declares no lifecycle
       def lifecycle_narrative(holder)
         lifecycle = holder.lifecycle or return nil
 
@@ -120,6 +163,13 @@ module Hecks
 
       # ── the verbs ─────────────────────────────────────────────────────
 
+      # Narrates every command a holder declares.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder whose
+      #   commands to narrate
+      # @param depth [Integer] the heading level for the "What can happen" section
+      # @return [String, nil] the section's Markdown prose, or nil if `holder`
+      #   declares no command
       def verbs_narrative(holder, depth)
         return nil if holder.commands.empty?
 
@@ -136,6 +186,10 @@ module Hecks
       # sentence depends on anything before it. Same nil-or-string +
       # `compact.join` shape `aggregate_narrative`/`entity_narrative`
       # already use above for the identical reason.
+      #
+      # @param command [Bluebook::Command] the command to narrate
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [String] the command's own paragraph
       def command_paragraph(command, holder)
         [
           command_headline_sentence(command),
@@ -153,10 +207,18 @@ module Hecks
       # exactly as declared, not recased to fit mid-sentence, because the
       # promise this whole projector makes is that a sentence here is a
       # sentence the chapter actually wrote.
+      #
+      # @param command [Bluebook::Command] the command to name
+      # @return [String] the command's own bold name, plus its goal if it declares one
       def command_headline_sentence(command)
         "**#{command.hecks_name}**#{command.goal ? " — #{command.goal}." : '.'}"
       end
 
+      # Names who issues a command.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence naming who issues `command`, or nil if it
+      #   declares no role
       def command_role_sentence(command)
         return nil unless command.role
 
@@ -168,12 +230,21 @@ module Hecks
       # `Command#acts_on`'s own comment), so reading it directly here would
       # tell an SME that `LedgerEntry.Amend` brings a new ledger entry into
       # being, which is exactly backwards.
+      # @param command [Bluebook::Command] the command to check
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [String, nil] a sentence saying `command` creates `holder`, or nil if
+      #   `command` acts on an existing record instead
       def command_creation_sentence(command, holder)
         return nil unless command.acts_on.nil?
 
         "This is how a new #{holder.hecks_name} comes into being."
       end
 
+      # Lists a command's own non-reference arguments.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence listing `command`'s non-reference arguments,
+      #   or nil if it declares none
       def command_arguments_sentence(command)
         arguments = command.attributes.reject(&:reference?)
         return nil if arguments.empty?
@@ -181,6 +252,11 @@ module Hecks
         "It takes #{to_sentence_list(arguments.map { |a| Forms::Humanize.label(a.name.to_s).downcase })}."
       end
 
+      # Names what a command references.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence naming what `command` references, or nil if
+      #   it declares no reference argument
       def command_references_sentence(command)
         refs = command.attributes.select(&:reference?)
         return nil if refs.empty?
@@ -188,6 +264,12 @@ module Hecks
         "It's aimed at one existing #{to_sentence_list(refs.map { |r| r.type.target_name })}, by id."
       end
 
+      # Lists a command's own required conditions.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [String, nil] a sentence listing every required condition, or nil if
+      #   `command` declares none
       def command_conditions_sentence(command, holder)
         conditions = conditions_of(command, holder)
         return nil if conditions.empty?
@@ -195,6 +277,11 @@ module Hecks
         "It only goes through if #{conditions.join('; ')}."
       end
 
+      # Lists what a command guarantees when it succeeds.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence listing `command`'s own `ensures`, or nil if
+      #   it declares none
       def command_guarantees_sentence(command)
         guarantees = command.ensures.map(&:description)
         return nil if guarantees.empty?
@@ -202,6 +289,11 @@ module Hecks
         "When it succeeds: #{guarantees.join('; ')}."
       end
 
+      # Names what a command records.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence naming what `command` records, or nil if it
+      #   emits nothing
       def command_emits_sentence(command)
         return nil if command.emits.empty?
 
@@ -214,6 +306,10 @@ module Hecks
       # `given`s), but kept positive rather than phrased as a refusal
       # reason. "Refused unless not X" is a sentence a reader has to
       # invert in their head; "only goes through if X" is not.
+      #
+      # @param command [Bluebook::Command] the command to gather conditions for
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [Array<String>] every required condition, stated positively
       def conditions_of(command, holder)
         conditions = []
 
@@ -234,6 +330,12 @@ module Hecks
 
       # ── the reads ─────────────────────────────────────────────────────
 
+      # Narrates every query as one line per question.
+      #
+      # @param queries [Array<Bluebook::Query>] the queries to narrate
+      # @param holder_name [String] the queries' own holder's name
+      # @param depth [Integer] the heading level for the "Questions you can ask" section
+      # @return [String, nil] the section's Markdown prose, or nil if `queries` is empty
       def queries_narrative(queries, holder_name, depth)
         return nil if queries.empty?
 
@@ -257,12 +359,23 @@ module Hecks
         "#{header}\n\n#{lines.join("\n")}"
       end
 
+      # Translates a query comparator into plain English.
+      #
+      # @param comparator [String, Symbol] a where-clause comparator, such as `:eq`
+      # @return [String] the comparator in plain words, or `comparator.to_s` verbatim
+      #   for one this file has no rendering rule for
       def op_words(comparator)
         { eq: "is", lt: "under", lte: "at most", gt: "over", gte: "at least" }[comparator.to_s.to_sym] || comparator.to_s
       end
 
       # ── what happens on its own ───────────────────────────────────────
 
+      # Narrates what happens on its own: every policy and every saga.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to narrate
+      # @param depth [Integer] the heading level for the "Reactions" section
+      # @return [String, nil] the section's Markdown prose, or nil if `bluebook`
+      #   declares no policy and no process manager
       def reactions_narrative(bluebook, depth)
         return nil if bluebook.policies.empty? && bluebook.process_managers.empty?
 
@@ -286,8 +399,16 @@ module Hecks
 
       # Both now live in `Naming` (a second projection, the glossary,
       # needed them); kept here as names so this file reads as it did.
+      #
+      # @param items [Array<#to_s>] items to join, in order
+      # @param conj [String] conjunction placed before the last item
+      # @return [String] the joined sentence fragment, `""` for an empty `items`
       def to_sentence_list(items, conj: "and") = Naming.to_sentence_list(items, conj: conj)
 
+      # Picks the English indefinite article for a word.
+      #
+      # @param word [String, Symbol] the word the article precedes
+      # @return [String] `"a"` or `"an"`
       def a_or_an(word) = Naming.a_or_an(word)
     end
   end

data/lib/hecks/projector/target.rb

@@ -55,11 +55,11 @@ module Hecks
       #
       # A capability says what a construct can do; this says what it must
       # carry. `:vocabulary` needs a chapter declaring a Vocabulary
-      # aggregate, `:parser_table` one declaring Syntax — and both used
-      # to state that as a `raise` in their own body, which is a
-      # requirement written as behaviour instead of declared. Stated
-      # here, the registry refuses before the projection runs and the
-      # projection stops carrying a guard about its own admission.
+      # aggregate, `:parser_table` one declaring Syntax — declared here
+      # rather than as a `raise` in the projection's own body, so the
+      # requirement is stated instead of written as behaviour. The
+      # registry refuses before the projection runs, so the projection
+      # itself no longer carries a guard about its own admission.
       # `emits:` says what kind of artifact comes back.
       #
       # `:artifact` (the default) is one thing — a Hash, or a String.
@@ -70,24 +70,61 @@ module Hecks
       # an ordinary Hash is guesswork — `{"name" => "Pizzas"}` is
       # indistinguishable from a one-file tree — so `write` asks what the
       # projection said rather than inspecting what it returned.
-      def projects_as(key, requires: nil, declares: nil, emits: :artifact)
-        @projection_emits    = emits
-        @projection_key      = key.to_sym
-        @projection_declares = Array(declares)
-        @projection_requires = Array(requires)
+      # Registers `self` as a projection target under `key`, and stores the
+      # capability and aggregate requirements `admits!` later checks against.
+      #
+      # @param key [String, Symbol] the key to register `self` under (converted to a symbol)
+      # @param requires [Module, Array<Module>, nil] capability module(s) a construct must
+      #   satisfy; nil or empty means `Bluebook::Behaviour::Chapter`
+      # @param declares [String, Symbol, Array<String, Symbol>, nil] aggregate name(s) the
+      #   chapter must declare; nil means none
+      # @param emits [Symbol] the kind of artifact `self` returns: `:artifact` (the default,
+      #   a single Hash or String) or `:files` (a path => contents tree)
+      # @param needs_world [Boolean] whether `self` is an export — a target that reads a
+      #   domain's `.world`/`.hecksagon` bindings, not only its declaration. `false` (the
+      #   default) for an ordinary projection; `true` refuses a `Projector.call` made with
+      #   no `world:`.
+      # @return [Symbol] the registered key
+      def projects_as(key, requires: nil, declares: nil, emits: :artifact, needs_world: false)
+        @projection_emits       = emits
+        @projection_key         = key.to_sym
+        @projection_declares    = Array(declares)
+        @projection_requires    = Array(requires)
+        @projection_needs_world = needs_world
         Projector.register(@projection_key, self)
         @projection_key
       end
 
+      # Gives the key this target registered under.
+      #
+      # @return [Symbol, nil] the key given to `projects_as`, or nil before it is called
       def projection_key = @projection_key
 
       # Empty means "a chapter" — resolved here rather than as a default
       # argument, because Behaviour::Chapter is not loaded yet when this
       # file is.
+      #
+      # @return [Array<String, Symbol>] aggregate names the chapter must declare; empty
+      #   for none
       def projection_declares = @projection_declares || []
 
+      # Gives the kind of artifact this target returns.
+      #
+      # @return [Symbol] the kind of artifact `self` returns: `:artifact` or `:files`
       def projection_emits = @projection_emits || :artifact
 
+      # Tells whether this target is an export — one that needs a domain's
+      # `.world`/`.hecksagon` bindings, passed as `Projector.call`'s `world:`,
+      # rather than only its declaration.
+      #
+      # @return [Boolean] the value given to `projects_as`' `needs_world:`, or false
+      #   before `projects_as` is called
+      def projection_needs_world? = @projection_needs_world || false
+
+      # Names the capability module(s) a construct must satisfy, defaulting
+      # to plain chapter-hood when `projects_as` named none.
+      #
+      # @return [Array<Module>] required capability modules
       def projection_requires
         req = @projection_requires
         req.nil? || req.empty? ? [Bluebook::Behaviour::Chapter] : req

data/lib/hecks/projector.rb

@@ -17,8 +17,11 @@ module Hecks
   # every real projection target (Rust/UL/OIDC all project one domain at
   # a time), and deliberately narrower than `Exporter.call`'s own
   # multi-domain shape.
-  # Three kinds of "PROJECT", told apart by what they need as input.
-  # Only the first belongs in this registry.
+  #
+  # ## Three kinds of "project"
+  #
+  # Told apart by what they need as input. Only the first belongs in this
+  # registry.
   #
   #   a projection takes a chapter's declaration and answers something
   #   that describes the domain: its IR, its storage shape, an OIDC scope
@@ -28,11 +31,13 @@ module Hecks
   #
   #   an export takes a declaration and its bindings and answers
   #   something that is the domain, running elsewhere — rust/project.rb's
-  #   generated crate, the WASM artifact, the SAM template
-  #   bin/project_deploy renders. It needs the `.world`/`.hecksagon` a
-  #   projection never looks at, because a running system has to know how
-  #   it is wired. That is the whole reason bin/project_deploy cannot use
-  #   this protocol: `call(bluebook:, options:)` has no channel for it.
+  #   generated crate, the WASM artifact, the CloudFormation template
+  #   `lib/hecks/projections/deploy` renders. It needs the
+  #   `.world`/`.hecksagon` a projection never looks at, because a
+  #   running system has to know how it is wired. A target that needs
+  #   this declares `needs_world: true` (`Target#projects_as`) and reads
+  #   `options.fetch(:world)`; `Projector.call`'s own `world:` keyword is
+  #   what carries it, merged into `options` before the target ever runs.
   #
   #   a state projection takes records — a domain after dispatch — and is
   #   a read-model question wearing the same word.
@@ -42,8 +47,10 @@ module Hecks
   #   dispatches. Converting it into this registry would be a category
   #   error, however much its name suggests otherwise.
   #
-  # **One word, three other meanings** — worth naming too, because grepping
-  # "projection" turns all of these up and none is the above:
+  # ## One word, three other meanings
+  #
+  # Worth naming too, because grepping "projection" turns all of these up
+  # and none is the above:
   #
   #   Ports::Projection    read-model catch-up, events folded into state
   #   bin/project          forces that catch-up by hand
@@ -61,24 +68,48 @@ module Hecks
     # deliberately unguarded: a spec re-registering a stub under the same
     # name between examples is the ordinary case, not a footgun to fence
     # against.
+    # Adds `projector` to the registry under `name`, replacing anything
+    # already registered there.
+    #
+    # @param name [String, Symbol] the key `projector` is looked up by (converted to a symbol)
+    # @param projector [Module, Class, #call] anything answering `call(bluebook:, options:)`
+    # @return [void]
     def register(name, projector)
       registry[name.to_sym] = projector
     end
 
+    # Runs the projector registered under `name` against `bluebook`,
+    # after refusing a construct it does not admit.
+    #
     # `bluebook:` is kept as the keyword because it is the shipped
     # spelling and every existing caller uses it — but what it accepts is
     # any construct that emits IR, and `admits!` is what decides whether
     # this target can actually take the one handed over.
-    def call(name, bluebook:, options: {})
+    #
+    # @param name [String, Symbol] the registered projector's key
+    # @param bluebook [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
+    #   IR-emitting construct to project
+    # @param options [Hash] projector-specific options, passed through unchanged
+    # @param world [Bluebook::World, nil] the domain's `.world`/`.hecksagon` bindings,
+    #   required by an export (`needs_world: true`); nil for an ordinary projection.
+    #   Merged into `options[:world]` before the target runs — the target never
+    #   receives it as a separate argument.
+    # @return [Object] whatever the projector's own `call` returns: typically a
+    #   `Hash`/`String` artifact, or a `Hash{String => String}` file tree
+    # @raise [UnknownProjector] if no projector is registered under `name`
+    # @raise [WrongConstruct] if `bluebook` lacks a capability or aggregate the
+    #   projector requires, or if the projector needs `world:` and none is given
+    def call(name, bluebook:, options: {}, world: nil)
       projector = registry.fetch(name.to_sym) do
         raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
       end
-      admits!(name, projector, bluebook)
-      projector.call(bluebook: bluebook, options: options)
+      admits!(name, projector, bluebook, world)
+      projector.call(bluebook: bluebook, options: world ? options.merge(world: world) : options)
     end
 
-    # A projection names the capabilities it needs; this refuses a
-    # construct that lacks one, before the projector runs.
+    # Refuses `construct` if it lacks a capability or declared aggregate
+    # `projector` requires. A projection names the capabilities it needs;
+    # this is what enforces that, before the projector runs.
     #
     # One check covers both shapes. An ordinary construct includes its
     # capabilities and a class-shaped one — Command, Entity, ValueObject
@@ -87,7 +118,21 @@ module Hecks
     # started as two checks on the assumption it would not; a spec
     # asserting the assumption failed, which is the only reason the
     # redundant half was noticed.
-    def admits!(name, projector, construct)
+    #
+    # @param name [String, Symbol] the projector's registered key, used in the message
+    #   when refusing
+    # @param projector [Module, Class, #call] the target being checked; consulted for
+    #   `projection_requires`, `projection_declares`, and `projection_needs_world?` when
+    #   it answers them
+    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
+    #   IR-emitting construct offered to the projector
+    # @param world [Bluebook::World, nil] the `world:` given to `Projector.call`, checked
+    #   against the target's own `needs_world:` declaration
+    # @return [void]
+    # @raise [WrongConstruct] if `construct` lacks a required capability, the chapter it
+    #   is declares no aggregate the projector needs, or the projector needs `world:`
+    #   and `world` is nil
+    def admits!(name, projector, construct, world = nil)
       needed = projector.respond_to?(:projection_requires) ? projector.projection_requires : []
       missing = needed.reject { |capability| capable?(construct, capability) }
       unless missing.empty?
@@ -98,25 +143,49 @@ module Hecks
 
       declared = projector.respond_to?(:projection_declares) ? projector.projection_declares : []
       absent   = declared.reject { |named| construct.aggregate(named) }
-      return if absent.empty?
+      unless absent.empty?
+        raise WrongConstruct,
+              "#{name.inspect} needs a chapter declaring #{absent.join(' and ')}; " \
+              "#{construct.name} declares no such aggregate."
+      end
+
+      return unless projector.respond_to?(:projection_needs_world?) && projector.projection_needs_world? && world.nil?
 
-      raise WrongConstruct,
-            "#{name.inspect} needs a chapter declaring #{absent.join(' and ')}; " \
-            "#{construct.name} declares no such aggregate."
+      raise WrongConstruct, "#{name.inspect} needs .world/.hecksagon bindings — pass world: to Projector.call."
     end
 
+    # Tells whether `construct` has the capability `admits!` requires of it.
+    #
+    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the construct to check
+    # @param capability [Module] the capability module to check for
+    # @return [Boolean] true if `construct` is a `capability`
     def capable?(construct, capability) = construct.is_a?(capability)
 
     # What kind of artifact a registered target emits — asked of the
     # projection rather than inferred from what it returned.
+    #
+    # @param name [String, Symbol] the registered projector's key
+    # @return [Symbol] `:files` for a path => contents tree, `:artifact` (the
+    #   default, including for an unregistered `name`) for a single Hash or String
     def emits_for(name)
       projector = registry.fetch(name.to_sym) { return :artifact }
       projector.respond_to?(:projection_emits) ? projector.projection_emits : :artifact
     end
 
+    # Tells whether a projector is registered under `name`.
+    #
+    # @param name [String, Symbol] the key to look up
+    # @return [Boolean] true if a projector is registered under `name`
     def registered?(name) = registry.key?(name.to_sym)
+
+    # Lists every key currently registered.
+    #
+    # @return [Array<Symbol>] every key currently registered
     def registered = registry.keys
 
+    # Gives the live registry, initializing it on first use.
+    #
+    # @return [Hash{Symbol => Module, Class, #call}] the live key => projector registry
     def registry
       @registry ||= {}
     end
@@ -126,6 +195,10 @@ module Hecks
     # (`:oidc`). Both resolve here, so the constant form is added
     # surface rather than a replacement — every `Projector.call(:ir, ...)`
     # written before this existed keeps working untouched.
+    #
+    # @param target [String, Symbol, #projection_key] a registered key, or a target
+    #   that declared its own key with `Target#projects_as`
+    # @return [String, Symbol] the key to call the target under
     def key_for(target)
       return target.projection_key if target.respond_to?(:projection_key) && target.projection_key
 
@@ -141,6 +214,11 @@ module Hecks
     # than from inspecting the artifact. A Hash of path => contents and a
     # Hash that simply happens to hold strings are the same object to
     # Ruby; only the projection knows which it meant.
+    #
+    # @param artifact [Hash, String] the projector's output; a file tree when `as: :files`
+    # @param out [String] the path to write to; a directory when `as: :files`
+    # @param as [Symbol] `:files` to write a tree, anything else to write one file
+    # @return [String, Array<String>] the path written, or every path written when `as: :files`
     def write(artifact, out, as: :artifact)
       return write_tree(artifact, out) if as == :files
 
@@ -150,6 +228,10 @@ module Hecks
 
     # Answers the paths written, in the order given — so a caller can
     # report what happened without re-deriving it from the tree.
+    #
+    # @param files [Hash{String => String}] relative path => contents
+    # @param directory [String] the directory to write the tree under
+    # @return [Array<String>] each file's full written path, in `files`' order
     def write_tree(files, directory)
       require "fileutils"
       files.map do |relative, contents|