hecks 1.3.0 → 1.5.0

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

@@ -1,32 +1,19 @@
 module Hecks
   module Projections
     module Model
-      # HOW THE MODEL'S SHAPE DIFFERS FROM THE LANGUAGE'S, and why.
+      # 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
+      # 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
+      # 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.
       module Deviations
-        # 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 — so both spellings are checked. Entity spells its own
-        # (separate, non-colliding) text twin of the parent link `owner`.
-        PARENT_REF = ->(field) { field.to_s.match?(/_id\z/) || %i[owner aggregate bluebook].include?(field) }
-
-        # The judge's own field, never the model's — contracts.rb already
-        # says so with `derived: { position: :walk }`.
-        JUDGE_ONLY = %i[position].freeze
-
         # What the model holds that the grammar declares elsewhere: the
         # containment edges, stated in syntax.bluebook's Keyword rows as
         # `context` -> `opens`.
@@ -64,7 +51,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
+        # **Declared, and deliberately not emitted**. The category that had no
         # home anywhere before — each of these was a comment and nothing
         # more.
         OFF_THE_WIRE = {
@@ -85,13 +72,71 @@ module Hecks
 
         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.
+        #
+        # @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

@@ -3,22 +3,22 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE MODEL CLASSES, PROJECTED FROM THE LANGUAGE THAT DECLARES THEM.
+    # The model classes, projected from the language that declares them.
     #
-    # A construct's HOLDING half — its readers, its emission, a
+    # A construct's holding half — its readers, its emission, a
     # constructor that assigns declared fields and hands off — restates
     # what `bluebook.bluebook` already says, three times over in Ruby.
     # This renders it instead.
     #
-    # ONLY THE HOLDING HALF. `Behaviour::X` is hand-written and permanent,
+    # **Only the holding half**. `Behaviour::X` is hand-written and permanent,
     # and `settle` is the seam: everything a declaration cannot state
     # lives behind it, so regenerating can never be lossy. That property
     # was established construct by construct before any of this was
     # 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;
-    # it does not state which constructs are Ruby CLASSES rather than
+    # 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
     # bluebooks, so they are declared here rather than pretended into the
@@ -29,7 +29,7 @@ module Hecks
 
       projects_as :model, declares: "Bluebook", emits: :files
 
-      # PER-CONSTRUCT RUBY FACTS. `coerce` is the only fiddly column: a
+      # **Per-construct Ruby facts**. `coerce` is the only fiddly column: a
       # declared field arrives as whatever the builder handed over, and
       # each construct has always normalised its own on the way in.
       HOST = {
@@ -37,21 +37,25 @@ module Hecks
           construct: "Policy",
           file:      "policy.rb",
           behaviour: "Behaviour::Policy",
-          readers:   %i[name on_event trigger_command target_domain where for_each with_spec],
+          readers:   %i[name on_event trigger_command target_domain expect_undelivered where for_each with_spec],
           accessors: %i[aggregate],
           defaults:  { name: nil, on_event: "nil", trigger_command: "nil",
-                       target_domain: "nil", where: "nil", for_each: "nil",
+                       target_domain: "nil", expect_undelivered: "false", where: "nil", for_each: "nil",
                        with_spec: "[]", aggregate: "nil" },
-          coerce:    { name: ".to_s", aggregate: "&.to_s" },
-          # A LIST OF BINDINGS IS NOT A SCALAR ON THE WIRE. Every other
+          # A flag on the wire is a boolean — the language holds it as
+          # text ("true"), the builder hands over `true`, and a
+          # reconstruction hands back whichever it read; all three land
+          # as the same `true`/`false`.
+          coerce:    { name: ".to_s", aggregate: "&.to_s", expect_undelivered: ".to_s == \"true\"" },
+          # A list of bindings is not a scalar on the wire. Every other
           # field emits as itself; this one has to render the way
           # `DispatchSpec`'s own `with_spec` does — keys to strings, and
-          # `render_value` KEEPING the leading colon on a Symbol, because
+          # `render_value` keeping the leading colon on a Symbol, because
           # a binding that reads an event field and one that supplies a
           # literal string are otherwise indistinguishable once written
           # down (see `MetaValidator::Readings`' own note on exactly that).
           renders:   { with_spec: "-> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }",
-                       # COMPUTED (Deviations::COMPUTED["Policy"]): the structured
+                       # Computed (Deviations::COMPUTED["Policy"]): the structured
                        # form of `where`, a pure function of that text, the same
                        # `ast` every rule row carries beside its `canonical`.
                        where_ast: "-> { where_ast }" },
@@ -61,14 +65,30 @@ 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.
-          # DO NOT EDIT: the holding half is rendered, and #{host.fetch(:behaviour)}
+          # Generated — projected from the language's own #{name} aggregate.
+          # Do not edit: the holding half is rendered, and #{host.fetch(:behaviour)}
           # is where anything hand-written belongs.
           require_relative "behaviour/#{File.basename(host.fetch(:file), '.rb')}"
 
@@ -91,9 +111,14 @@ module Hecks
 
       # The emission, keyed as the model spells it and sourced as the
       # language declares it.
-      # A COMPUTED field (Deviations::COMPUTED) is emitted too — it is
+      # 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`.
+      # 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, {})
@@ -102,37 +127,54 @@ module Hecks
         "emits_ir(\n#{fields.map { |f| "  #{"#{f}:".ljust(width + 1)} #{renders.fetch(f, ":#{f}")}" }.join(",\n")}\n)"
       end
 
-      # WHAT THE CONSTRUCT EMITS: what the language declares, less every
+      # What the construct emits: what the language declares, less every
       # 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.call(f) } -
-          Deviations::JUDGE_ONLY -
+                .reject { |f| Deviations.parent_ref?(f) } -
+          Deviations.judge_only(name) -
           Deviations.off_the_wire(name) -
           Deviations.dynamic_tail(name) -
           Deviations.folded(name).values.flatten -
           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, [])
         return lines.join("\n") if accessors.empty?
 
         # A declared field the model deliberately does not emit still
-        # needs a reader, and the REASON it is off the wire is carried
+        # needs a reader, and the reason it is off the wire is carried
         # here rather than typed in — a comment that survives
         # regeneration is one the generator writes.
         reasons = Deviations::OFF_THE_WIRE.fetch(host.fetch(:construct, ""), {})
         (lines + accessors.map do |a|
           why = reasons[a]
-          (why ? "\n# #{a.upcase}, DECLARED AND DELIBERATELY OFF THE WIRE\n# #{wrap(why)}\n" : "") +
+          (why ? "\n# #{a.to_s.capitalize}, declared and deliberately off the wire\n# #{wrap(why)}\n" : "") +
             "attr_accessor :#{a}"
         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|
@@ -143,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

@@ -3,16 +3,17 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # AN OIDC CLIENT/SCOPE MANIFEST derived from a domain's own IR: what
+    # An OIDC client/scope manifest derived from a domain's own IR: what
     # 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.
-    # `spec/oidc_projection_spec.rb` covers the INTEGRATION half — verified
+    # ## 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
     # a role per command. It just had no way to say, up front and as data,
-    # WHICH role each command wants — every answer came from asking the
+    # which role each command wants — every answer came from asking the
     # live runtime one dispatch at a time.
     #
     # This is that catalogue, and the two are checked against each other
@@ -24,12 +25,13 @@ 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
-    # available here AND the more accurate source: it says what each
+    # available here and the more accurate source: it says what each
     # command actually demands, not merely which role vocabulary the
     # application happened to mount.
     #
@@ -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)}"
@@ -93,9 +121,18 @@ module Hecks
       end
 
       # `banking:account.open` — the shape an OIDC scope is conventionally
-      # spelled in, and snake_cased through the SAME `Naming.snake` the
+      # 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|
           {

data/lib/hecks/projections/parser_table.rb

@@ -2,12 +2,12 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE RUST PARSER'S KEYWORD TABLE, projected from the chapter's own
-    # Syntax aggregate — "the parser's grammar knowledge is DERIVED from
+    # The Rust parser's keyword table, projected from the chapter's own
+    # Syntax aggregate — "the parser's grammar knowledge is derived from
     # hecks's self-description, not hand-typed a second time", which
     # is the anti-drift idea the whole Rust-parser plan rests on.
     #
-    # A REGISTERED TARGET NOW, rather than a module living inside its own
+    # A registered target now, rather than a module living inside its own
     # bin/ script. It was already a projection in everything but call
     # shape; this only stops it being a fifth way of spelling one.
     module ParserTable
@@ -16,25 +16,47 @@ module Hecks
 
       module_function
 
+      # Projects the Rust parser's keyword and closed-set tables for one chapter.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project; the language's own
+      #   for the ordinary `bin/project_parser_table` run
+      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
+      #   `Projector::Target` calling convention
+      # @return [String] the rendered Rust source
       def call(bluebook:, options: {}) = render(bluebook)
 
       module_function
 
-      # THE CHAPTER IS HANDED OVER, not reached for. This used to open the
-      # grammar registry itself, which meant the projection could only ever
-      # project one chapter — the language's own. Taking it as an argument is
-      # what the projector protocol asks for, and it costs nothing.
+      # The chapter is handed over, not reached for — reaching for the grammar
+      # registry directly would pin the projection to one chapter, the language's
+      # own, and the projector protocol already hands over the chapter as an
+      # argument, at no cost.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to read the Syntax aggregate
+      #   from
+      # @return [Bluebook::Aggregate, nil] the chapter's `"Syntax"` aggregate, `nil` if
+      #   it declares none
       def syntax(bluebook) = bluebook.aggregate("Syntax")
 
       # Every cell as text — exactly spec/syntax_conformance_spec.rb's own
       # `rows` helper, reused rather than re-derived: a member's fields decode
       # back through typed literal decoding on the way out of reconstruction,
       # and this reads it back as what was written.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to read from
+      # @param name [String] the closed-set value object's name, such as `"Context"`
+      # @return [Array<Hash{Symbol => String}>] one row per declared member, every
+      #   field stringified
       def rows(bluebook, name)
         syntax(bluebook).value_objects.find { |vo| vo.hecks_name == name }
               .members.map { |row| row.to_h.transform_values(&:to_s) }
       end
 
+      # Reads one closed set's member names, for a Rust `&[&str]` constant.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to read from
+      # @param name [String] the closed-set value object's name
+      # @return [Array<String>] every declared member's `:name` field
       def closed_set_members(bluebook, name) = rows(bluebook, name).map { |row| row[:name] }
 
       KEYWORD_FIELDS  = %i[word context body inner opens fills status was resolves_via disambiguator].freeze
@@ -45,18 +67,34 @@ module Hecks
       # plain ASCII (a word, a context name, a digit, "true"/"false"), so this
       # only has to be safe against the two characters Rust string literals
       # themselves reserve.
+      #
+      # @param value [Object] the field value to render; stringified before escaping
+      # @return [String] a quoted Rust string literal
       def rust_string(value) = "\"#{value.to_s.gsub('\\', '\\\\\\\\').gsub('"', '\\"')}\""
 
+      # Renders one `KEYWORDS` table entry.
+      #
+      # @param row [Hash{Symbol => String}] one keyword row, keyed by `KEYWORD_FIELDS`
+      # @return [String] one `KeywordRow { ... },` line
       def keyword_row(row)
         fields = KEYWORD_FIELDS.map { |field| rust_string(row[field]) }
         "    KeywordRow { #{KEYWORD_FIELDS.zip(fields).map { |name, value| "#{name}: #{value}" }.join(', ')} },"
       end
 
+      # Renders one `ARGUMENTS` table entry.
+      #
+      # @param row [Hash{Symbol => String}] one argument row, keyed by `ARGUMENT_FIELDS`
+      # @return [String] one `ArgumentRow { ... },` line
       def argument_row(row)
         fields = ARGUMENT_FIELDS.map { |field| rust_string(row[field]) }
         "    ArgumentRow { #{ARGUMENT_FIELDS.zip(fields).map { |name, value| "#{name}: #{value}" }.join(', ')} },"
       end
 
+      # Renders one `pub static NAME: &[&str]` constant.
+      #
+      # @param name [String] the Rust constant's name
+      # @param values [Array<String>] the constant's member strings
+      # @return [String] the rendered `pub static` declaration
       def const_str_array(name, values)
         lines = values.map { |value| "    #{rust_string(value)}," }
         "pub static #{name}: &[&str] = &[\n#{lines.join("\n")}\n];\n"
@@ -64,12 +102,15 @@ module Hecks
 
       # S14, ADR 0026 — Keyword/Argument are genuine entities of Syntax
       # now, dispatched (not merely declared) so their own `status`
-      # really is a lifecycle. `SyntaxBoot.call` reads the STILL-STATIC
+      # really is a lifecycle. `SyntaxBoot.call` reads the still-static
       # seed rows (`KeywordSeed`/`ArgumentSeed`), dispatches each one
-      # through the real admission/lifecycle door, and hands back the
-      # exact same shape `rows` used to read straight off the closed set
-      # — symbol keys, string values, `status` included — so nothing
-      # else in this file needed to change.
+      # through the real admission/lifecycle door, and hands back rows in
+      # the same shape `rows` reads for every other closed set here —
+      # symbol keys, string values, `status` included — so nothing else
+      # in this file needs to change.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @return [String] the rendered `KEYWORDS`/`ARGUMENTS`/closed-set Rust source
       def render(bluebook)
         table     = Hecks::Bluebook::MetaValidator::SyntaxBoot.call
         keywords  = table[:keywords]

data/lib/hecks/projections/reference.rb

@@ -3,18 +3,18 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE DSL REFERENCE PAGES, projected from the chapter's own Syntax
+    # The DSL reference pages, projected from the chapter's own Syntax
     # aggregate — the tables come from the declaration, the prose is
     # preserved from whatever is already committed.
     #
-    # THE FIRST PROJECTION THAT EMITS A TREE. `emits: :files` says so,
+    # The first projection that emits a tree. `emits: :files` says so,
     # and the framework writes the map rather than inferring one: a Hash
     # of path => contents and a Hash that merely holds strings are the
     # same object to Ruby, so only the projection can know which it
     # meant. This is the case the output contract was designed for and
     # deliberately left unimplemented until something real needed it.
     #
-    # NOT PURE, and it cannot be. `Doc::Reference.pages` READS the
+    # Not pure, and it cannot be. `Doc::Reference.pages` reads the
     # committed pages to harvest their prose, so the existing directory
     # is an input — passed as `from:` rather than assumed, so the
     # projection never reaches for a path of its own choosing.
@@ -25,6 +25,18 @@ module Hecks
 
       module_function
 
+      # Renders one reference page per DSL keyword context, carrying prose
+      # over from whatever is already committed under `options[:from]`.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Syntax aggregate to render pages from; unused beyond admission, since the
+      #   keyword table this reads comes from the global `Syntax` grammar
+      # @param options [Hash] must include `:from`
+      # @option options [String] :from directory holding the already-committed
+      #   reference pages, read to harvest their prose
+      # @return [Hash{String => String}] each page's filename => its rendered
+      #   Markdown, including `"index.md"`
+      # @raise [ArgumentError] if `options[:from]` is missing or falsy
       def call(bluebook:, options: {})
         from = options[:from] or
           raise ArgumentError,