hecks 1.3.0 → 1.5.0

data/lib/hecks/projector/docs_projector.rb

@@ -2,48 +2,65 @@ require_relative "../naming"
 
 module Hecks
   module Projector
-    # A BLUEBOOK, PROJECTED AS ITS OWN USAGE DOCUMENTATION.
+    # A bluebook, projected as its own usage documentation.
     #
-    # WHAT THIS IS FOR. A chapter in this corpus already contains everything a
-    # user of it needs: what each aggregate is (`description`), what each verb
-    # is for (`goal`) and who issues it (`role`), which states it moves
+    # ## What this is for
+    #
+    # A chapter in this corpus already contains everything a user of it
+    # needs: what each aggregate is (`description`), what each verb is
+    # for (`goal`) and who issues it (`role`), which states it moves
     # between, what it refuses and in whose words (`given`, `invariant`,
-    # `ensures`), and what each list is worth reading (`description` on a
-    # query). None of that reaches the person who has to CALL the domain.
-    # They read the source, or they read a document somebody wrote beside the
-    # source and stopped updating.
+    # `ensures`), and what each list is worth reading (`description` on
+    # a query). None of that reaches the person who has to call the
+    # domain. They read the source, or they read a document somebody
+    # wrote beside the source and stopped updating.
     #
     # `docs/implemented/reference/` is the precedent and the contrast. `bin/reference`
     # generates it from the language's own Syntax chapter, so the reference
     # for the DSL cannot drift from the DSL. This is the same trick one level
-    # down: the usage document for a DOMAIN, generated from that domain, so it
+    # down: the usage document for a domain, generated from that domain, so it
     # cannot drift from the domain either.
     #
-    # WHY IT IS A PROJECTION AND NOT A GENERATOR SCRIPT. `Projector` is the
-    # repository's registry of "canonical IR in, external artifact out" (§30
-    # of the implementation plan), and this is exactly that shape: one
-    # bluebook's IR in, markdown out, no runtime needed and no store touched.
-    # Registered as `:docs` beside `:ir`, and reachable the way every
-    # projector is — `Projector.call(:docs, bluebook: ...)`.
+    # ## Why a projection, not a generator script
+    #
+    # `Projector` is the repository's registry of "canonical IR in,
+    # external artifact out" (§30 of the implementation plan), and this
+    # is exactly that shape: one bluebook's IR in, markdown out, no
+    # runtime needed and no store touched. Registered as `:docs` beside
+    # `:ir`, and reachable the way every projector is —
+    # `Projector.call(:docs, bluebook: ...)`.
     #
-    # AND AS A METHOD, which is the half that makes it get used.
+    # And as a method, which is the half that makes it get used.
     # `Facade::Surface` already installs a module per chapter carrying
     # `vision` and `aggregates`; `docs` joins them, so a booted domain answers
     # `QualityControl.docs` and an aggregate door answers
     # `QualityControl::Bug.docs`. A document you have to remember a script for
     # is a document nobody reads.
     #
-    # WHAT IT DELIBERATELY DOES NOT DO: invent. Every sentence below comes out
-    # of the chapter. Where a chapter says nothing — an aggregate with no
-    # `description`, a command with no `goal` — the document says nothing
-    # rather than filling the gap with a restatement of the name, because a
-    # generated paragraph that only rephrases an identifier teaches a reader
-    # to skim the ones that do not.
+    # ## What it deliberately does not do
+    #
+    # Invent. Every sentence below comes out of the chapter. Where a
+    # chapter says nothing — an aggregate with no `description`, a
+    # command with no `goal` — the document says nothing rather than
+    # filling the gap with a restatement of the name, because a
+    # generated paragraph that only rephrases an identifier teaches a
+    # reader to skim the ones that do not.
     module DocsProjector
       module_function
 
+      # Projects `bluebook` as its own usage documentation.
+      #
       # `options[:heading]` sets the top heading level (default 1), so a
       # caller splicing this into a larger document can push it down.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to document
+      # @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 document to one
+      #   aggregate, omitting the chapter header and closing sections
+      # @return [String] the document, as Markdown, 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]
@@ -55,11 +72,18 @@ module Hecks
         "#{out.compact.join("\n").rstrip}\n"
       end
 
-      # A NAME THAT NAMES NOTHING IS REFUSED, not answered with an empty
+      # A name that names nothing is refused, not answered with an empty
       # document. Shipped the other way first: `options[:aggregate]` that
       # matched no head returned "" and exit 0, which is the silent-wrong-
       # answer shape this repository has already been bitten by twice in the
       # query engine. A misspelling should cost a sentence, not a puzzle.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to look in
+      # @param only [String, Symbol, nil] narrows the result to the one aggregate
+      #   named; nil answers every aggregate
+      # @return [Array<Bluebook::Aggregate>, Bluebook::Aggregate] every declared
+      #   aggregate, or the single aggregate `only` names
+      # @raise [Runtime::NotFound] if `only` names no aggregate `bluebook` declares
       def aggregates(bluebook, only)
         return bluebook.aggregates unless only
 
@@ -69,13 +93,24 @@ module Hecks
                 "it declares #{bluebook.aggregates.map(&:hecks_name).sort.join(', ')}")
       end
 
+      # Renders a Markdown heading line.
+      #
+      # @param depth [Integer] the heading level
+      # @param text [String] the heading text
+      # @return [String] a Markdown `#`-prefixed heading line
       def h(depth, text) = "#{'#' * depth} #{text}"
 
       # ── the chapter ───────────────────────────────────────────────────
 
+      # Renders the chapter-level header: its title, vision, classification,
+      # former name, and aggregate list.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to document
+      # @param depth [Integer] the heading level for the chapter's own title
+      # @return [String] the header's Markdown source
       def chapter_header(bluebook, depth)
         out = [h(depth, bluebook.name), ""]
-        # THE VISION FIRST AND AS A QUOTE. It is the one sentence in a chapter
+        # The vision first and as a quote. It is the one sentence in a chapter
         # written for somebody who does not know the domain yet.
         out += ["> #{bluebook.vision}", ""] if bluebook.vision
         out << "#{bluebook.classification.to_s.capitalize} domain." if bluebook.classification
@@ -86,13 +121,22 @@ module Hecks
         out.join("\n")
       end
 
+      # Builds a construct's own GitHub-style heading anchor.
+      #
+      # @param name [String, Symbol] the construct name to anchor
+      # @return [String] the construct's own GitHub-style heading anchor
       def anchor(name) = Naming.snake(name).tr("_", "-")
 
-      # WHAT HAPPENS WITHOUT ANYBODY ASKING — the part of a domain a caller
+      # What happens without anybody asking — the part of a domain a caller
       # cannot discover from any verb list, and the part most likely to surprise
       # them. A policy means one dispatch causes another, sometimes into a
       # different domain entirely; a saga means a sequence is being driven on
       # their behalf and can end in more than one place.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to document
+      # @param depth [Integer] the heading level for the "Reactions"/saga sections
+      # @return [String, nil] the closing's Markdown source, or nil if `bluebook`
+      #   declares no policy and no process manager
       def closing(bluebook, depth)
         out = []
 
@@ -123,6 +167,12 @@ module Hecks
 
       # ── one aggregate ─────────────────────────────────────────────────
 
+      # Documents one aggregate: its description, identity, references,
+      # attributes, lifecycle, verbs, queries, and nested entities.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate to document
+      # @param depth [Integer] the heading level for the aggregate's own title
+      # @return [String] the aggregate's Markdown section
       def aggregate_section(aggregate, depth)
         out = [h(depth, aggregate.hecks_name), ""]
         out += [aggregate.description, ""] if aggregate.description
@@ -142,10 +192,16 @@ module Hecks
         out.compact.join("\n")
       end
 
+      # Documents one entity nested under `aggregate`.
+      #
+      # @param aggregate [Bluebook::Aggregate] the entity's own owning aggregate
+      # @param entity [Bluebook::Entity] the entity to document
+      # @param depth [Integer] the heading level for the entity's own title
+      # @return [String] the entity's Markdown section
       def entity_section(aggregate, entity, depth)
         out = [h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})"), ""]
         out += [entity.description, ""] if entity.description
-        # THE THING A CALLER GETS WRONG FIRST. An entity has no door of its
+        # The thing a caller gets wrong first. An entity has no door of its
         # own: its verb is spelled through the aggregate that holds it, and
         # the parent's id travels alongside the entity's own identity.
         out << "Addressed through its holder — `#{aggregate.hecks_name}.#{entity.hecks_name}.<Verb>`, " \
@@ -161,6 +217,12 @@ module Hecks
 
       # ── the shape ─────────────────────────────────────────────────────
 
+      # Renders a holder's own non-reference attributes as a Markdown table.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder whose
+      #   attributes to render
+      # @return [String, nil] the attribute/shape/rules table, or nil if `holder`
+      #   declares no non-reference attribute
       def attributes_table(holder)
         attributes = holder.attributes.reject(&:reference?)
         return nil if attributes.empty?
@@ -171,10 +233,15 @@ module Hecks
         table(%w[attribute shape rules], rows)
       end
 
-      # A VALUE OBJECT'S FIELDS, NOT ITS NAME. `commit` typed `CommitRef` tells
+      # A value object's fields, not its name. `commit` typed `CommitRef` tells
       # a caller nothing; `{ value: String }` tells them what to send, which is
       # the single most common thing to get wrong at this boundary — a bare
       # scalar where an object is wanted.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to describe
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `attribute`'s own holder
+      # @return [String] the attribute's shape: its value object's own fields, or its
+      #   scalar type, with "list of" and "*(optional)*" applied as declared
       def shape_of(attribute, holder)
         value_object = value_object_for(attribute, holder)
         inner =
@@ -187,6 +254,12 @@ module Hecks
         attribute.optional? ? "#{shape} *(optional)*" : shape
       end
 
+      # Lists an attribute's own rules: closed-set members, field patterns and
+      # defaults, invariants, and its own default.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to describe
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `attribute`'s own holder
+      # @return [String] the attribute's rules, joined with "; "; `""` if it has none
       def rules_of(attribute, holder)
         value_object = value_object_for(attribute, holder)
         rules = []
@@ -200,6 +273,11 @@ module Hecks
         rules.empty? ? "" : rules.join("; ")
       end
 
+      # Names a closed set's own members.
+      #
+      # @param value_object [Bluebook::ValueObject, nil] the value object to check
+      # @return [Array<Object>] every unique value across `value_object`'s own member
+      #   rows, or `[]` if `value_object` is nil or not a closed set
       def closed_members(value_object)
         return [] unless value_object&.closed_set?
 
@@ -208,6 +286,12 @@ module Hecks
 
       # An entity holds no value objects of its own — its argument types are
       # declared on the aggregate above it.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute whose type to resolve
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `attribute`'s own holder
+      # @return [Bluebook::ValueObject, nil] the value object class `attribute`'s type
+      #   names, found on `holder` or its own owning aggregate; nil if `attribute`'s
+      #   type is not a value object
       def value_object_for(attribute, holder)
         scopes = [holder, holder.respond_to?(:hecks_owner) ? holder.hecks_owner : nil].compact
         scopes.each do |scope|
@@ -221,6 +305,13 @@ module Hecks
 
       # ── the machine ───────────────────────────────────────────────────
 
+      # Renders a holder's own lifecycle as a "starting state" sentence and a
+      # verb/from/to table.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to document
+      # @param depth [Integer] the heading level for the "Lifecycle" section
+      # @return [String, nil] the section's Markdown source, or nil if `holder`
+      #   declares no lifecycle
       def lifecycle_section(holder, depth)
         lifecycle = holder.lifecycle or return nil
 
@@ -234,6 +325,13 @@ module Hecks
 
       # ── the verbs ─────────────────────────────────────────────────────
 
+      # Documents every command a holder declares.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder whose
+      #   commands to document
+      # @param depth [Integer] the heading level for the "Verbs" section
+      # @return [String, nil] the section's Markdown source, or nil if `holder`
+      #   declares no command
       def verbs_section(holder, depth)
         commands = holder.commands
         return nil if commands.empty?
@@ -243,6 +341,13 @@ module Hecks
         out.join("\n")
       end
 
+      # Documents one command: its goal, role, arguments, refusals,
+      # guarantees, and emitted events.
+      #
+      # @param command [Bluebook::Command] the command to document
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @param depth [Integer] the heading level for the command's own title
+      # @return [String] the command's Markdown section
       def command_entry(command, holder, depth)
         out = [h(depth, "#{command.hecks_name}#{' *(creates)*' if command.creates?}"), ""]
         out += [command.goal, ""] if command.goal
@@ -270,6 +375,11 @@ module Hecks
       # nothing to share with `command_entry`'s other sections, extracted
       # only to keep that method to the one shape every section there
       # follows: build a chunk, append it if non-empty.
+      #
+      # @param arguments [Array<Bluebook::Attribute>] the command's own arguments
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the arguments' own holder
+      # @return [Array<Array(String, String, String)>] one `[argument, shape, needed]`
+      #   row per argument
       def command_argument_rows(arguments, holder)
         arguments.map do |attribute|
           shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : shape_of(attribute, holder)
@@ -277,11 +387,15 @@ module Hecks
         end
       end
 
-      # EVERY WAY THIS VERB CAN SAY NO, gathered from the three places a
+      # Every way this verb can say no, gathered from the three places a
       # chapter states them — the lifecycle it is an edge of, its own
       # `given`s, and the fact that a reference has to resolve. A caller
       # reading only the argument list learns none of these, and they are
       # most of what a domain is.
+      #
+      # @param command [Bluebook::Command] the command to gather refusals for
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [Array<String>] every way `command` can refuse, stated as sentences
       def refusals_of(command, holder)
         refusals = []
 
@@ -304,6 +418,12 @@ module Hecks
 
       # ── the reads ─────────────────────────────────────────────────────
 
+      # Renders a list of queries as one Markdown paragraph per query.
+      #
+      # @param queries [Array<Bluebook::Query>] the queries to document
+      # @param depth [Integer] the heading level for `title`
+      # @param title [String] the section's own heading text
+      # @return [String, nil] the section's Markdown source, or nil if `queries` is empty
       def queries_section(queries, depth, title)
         return nil if queries.empty?
 
@@ -320,6 +440,12 @@ module Hecks
         out.join("\n")
       end
 
+      # Renders a Markdown pipe table.
+      #
+      # @param headers [Array<String>] the column headers
+      # @param rows [Array<Array<String>>] each row's own cell values, matching
+      #   `headers`' width
+      # @return [String] the rendered table, ending in a blank line
       def table(headers, rows)
         lines = ["| #{headers.join(' | ')} |", "|#{headers.map { '---' }.join('|')}|"]
         rows.each { |row| lines << "| #{row.join(' | ')} |" }

data/lib/hecks/projector/exporter.rb

@@ -5,31 +5,39 @@ module Hecks
   module Projector
     # Registry-wide serialization to Hash/JSON: bluebook IR
     # (`call`/`json`), era-adapter lineage-capability flags (`lineage`),
-    # and translation edges in both their DIGEST-relevant declared shape
+    # and translation edges in both their digest-relevant declared shape
     # (`translation_hash`, what ApprovalDigest hashes) and their
-    # consumer-ready COMPILED shape with precompiled SQL attached
+    # consumer-ready compiled shape with precompiled SQL attached
     # (`translations`/`compiled_translation_aggregate`). Read directly by
     # bin/ir, bin/project_rust, and the translation/audit approval digest.
     module Exporter
       module_function
 
+      # Exports every booted bluebook's own canonical IR.
+      #
+      # @param registry [Runtime::Registry] the booted registry to export
+      # @return [Hash{String => Hash}] each domain name, mapped to its bluebook's `to_h`
       def call(registry)
         registry.bluebooks.transform_values(&:to_h)
       end
 
+      # Exports every booted bluebook's own canonical IR as JSON.
+      #
+      # @param registry [Runtime::Registry] the booted registry to export
+      # @return [String] `call`'s output, as pretty-printed JSON
       def json(registry)
         JSON.pretty_generate(call(registry))
       end
 
-      # A BINDING fact, deliberately NOT folded into `call`/`bluebook.to_h`
+      # A binding fact, deliberately not folded into `call`/`bluebook.to_h`
       # above — the canonical IR is runtime-independent by design (ADR
-      # 0001: it describes what a bluebook DECLARES, never which adapter
+      # 0001: it describes what a bluebook declares, never which adapter
       # a deployment happens to bind it to), and "is this aggregate bound
       # to a lineage-capable adapter" is exactly the kind of fact that
       # answer can change per-deployment without the bluebook's own shape
       # changing at all. Consumers that need it (bin/project_rust's own
       # `ir.json` sidecar, rust/host's runtime era-aware seed overlay —
-      # dispatch.rs) merge this in as a SEPARATE top-level key, the same
+      # dispatch.rs) merge this in as a separate top-level key, the same
       # way `translations` already sits beside `call`'s output rather than
       # inside it.
       #
@@ -42,6 +50,12 @@ module Hecks
       # already answers for a domain with nothing lineage-capable bound —
       # `capable_aggregates: []` — rather than raising on an undefined
       # constant.
+      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+      # @param domain_name [String] the domain to check era-adapter lineage capability for
+      # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:capable_aggregates`,
+      #   each a `:name`/`:storage_name` Hash; empty when the era plugin is unloaded or
+      #   nothing this domain binds is lineage-capable
+      # @raise [KeyError] if `domain_name` is not a loaded domain
       def lineage(registry, domain_name)
         return { capable_aggregates: [] } unless Ports::Persistence.plugin?(:era)
 
@@ -54,13 +68,13 @@ module Hecks
         { capable_aggregates: capable.map { |aggregate| { name: aggregate.name, storage_name: aggregate.storage_name } } }
       end
 
-      # A BINDING fact, same shape/reasoning as `lineage` above: every
-      # aggregate's DECLARED persistence adapter name (`persisted_by`),
+      # A binding fact, same shape/reasoning as `lineage` above: every
+      # aggregate's declared persistence adapter name (`persisted_by`),
       # not part of the canonical bluebook shape `call` exports (ADR
       # 0001 — the IR describes what's declared, never which adapter a
       # deployment binds it to). Unlike `lineage`, this needs no era
       # plugin — `BindingPolicy` is core, always loaded — and covers
-      # EVERY aggregate, not just lineage-capable ones: `rust/host`
+      # every aggregate, not just lineage-capable ones: `rust/host`
       # (`ir.rs`'s own `refuse_unsupported_persistence_adapters`) reads
       # this to refuse loudly, at boot, against a domain bound to an
       # adapter it has no backend for (Heki, Memory, Sqlite, D1,
@@ -68,6 +82,13 @@ module Hecks
       # today), rather than silently building up a second, disjoint
       # history nothing but Rust ever reads while the real state stays
       # wherever its own adapter actually wrote it.
+      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+      # @param domain_name [String] the domain to export persistence bindings for
+      # @return [Hash{Symbol => Array<Hash{Symbol => Object}>}] `:aggregates`, each a
+      #   `:name`/`:storage_name`/`:adapter` Hash
+      # @raise [KeyError] if `domain_name` is not a loaded domain
+      # @raise [Runtime::WiringError] if an aggregate has no authoritative bind, more
+      #   than one, or a bind with a role this port does not support
       def persistence(registry, domain_name)
         bluebook = registry.bluebooks.fetch(domain_name)
         aggregates = bluebook.aggregates.map do |aggregate|
@@ -78,7 +99,34 @@ module Hecks
         { aggregates: aggregates }
       end
 
-      # Translation IR, always as an array, WITH each aggregate's
+      # A binding fact, same shape/reasoning as `lineage`/`persistence`
+      # above: which chapter this domain's role checks resolve against
+      # (`Registry#authorization_provider_for` — the domain's own chapter
+      # or a framework member it attaches that declares `provides
+      # "authorization"`), with that chapter's declared verbs qualified.
+      # `rust/host` (auth.rs) reads this instead of naming Governance.
+      # `{}` when nothing this domain attaches provides authorization.
+      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+      # @param domain_name [String] the domain to export the authorization binding for
+      # @return [Hash{Symbol => String, nil}] `:provider` (name), `:grant`, `:assignments`
+      #   (both provided-verb names), and `:assignment_aggregate` (`:assignments`' own
+      #   leading aggregate name); `{}` if nothing this domain attaches provides
+      #   authorization
+      def authorization(registry, domain_name)
+        provider = registry.authorization_provider_for(domain_name)
+        return {} unless provider
+
+        capability = Bluebook::Capabilities::AUTHORIZATION
+        assignments = provider.provided_verb(capability, :assignments)
+        {
+          provider:             provider.name,
+          grant:                provider.provided_verb(capability, :grant),
+          assignments:          assignments,
+          assignment_aggregate: assignments&.split(".")&.first
+        }
+      end
+
+      # Translation IR, always as an array, with each aggregate's
       # precompiled SQL attached (`compiled_translation_aggregate`) —
       # this is the export a consumer embeds (`ir.json`'s `translations`
       # key), never the bare digest-relevant shape `edge_digest` hashes
@@ -86,10 +134,19 @@ module Hecks
       # separate). `values:` tables serialize as `[key, value]` pairs,
       # never an object, because JSON object keys are always strings and
       # a convert's keys are typed.
+      # @param registry [Runtime::Registry] the booted registry to export translations from
+      # @return [Array<Hash>] every registered translation, as `compiled_translation_hash`
+      #   builds
       def translations(registry)
         registry.translations.map { |translation| compiled_translation_hash(translation) }
       end
 
+      # Exports one translation, its aggregates' compiled SQL included.
+      #
+      # @param translation [Bluebook::Translation] the translation to export
+      # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
+      #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
+      #   (each `compiled_translation_aggregate`'s own Hash)
       def compiled_translation_hash(translation)
         {
           domain:     translation.domain,
@@ -100,21 +157,29 @@ module Hecks
         }
       end
 
+      # Exports every registered translation as JSON.
+      #
+      # @param registry [Runtime::Registry] the booted registry to export translations from
+      # @return [String] `translations`' output, as pretty-printed JSON
       def translations_json(registry)
         JSON.pretty_generate(translations(registry))
       end
 
-      # THE DIGEST-RELEVANT SHAPE — `ApprovalDigest.edge_digest` hashes
-      # EXACTLY this, and only this, for exactly the reason `compiled_
+      # The digest-relevant shape — `ApprovalDigest.edge_digest` hashes
+      # exactly this, and only this, for exactly the reason `compiled_
       # translation_aggregate` below must never be used for that
-      # purpose: a digest bound to the COMPILED SQL, not just the
-      # DECLARED rules, would invalidate an existing human approval the
+      # purpose: a digest bound to the compiled SQL, not just the
+      # declared rules, would invalidate an existing human approval the
       # moment `Translation::RuleCompiler`'s own output format changed
       # for any reason — a compiler refactor, a cosmetic SQL-formatting
       # change — even when the declared rules an approver actually
-      # reviewed never changed at all. The approval binds to WHAT WAS
-      # DECLARED, not to what a particular compiler build happened to
+      # reviewed never changed at all. The approval binds to what was
+      # declared, not to what a particular compiler build happened to
       # emit from it.
+      # @param translation [Bluebook::Translation] the translation to digest
+      # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
+      #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
+      #   (each `translation_aggregate`'s own Hash)
       def translation_hash(translation)
         {
           domain:     translation.domain,
@@ -125,6 +190,14 @@ module Hecks
         }
       end
 
+      # Digests one aggregate's own declared translation rules.
+      #
+      # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
+      #   translation rules to digest
+      # @return [Hash{Symbol => Object}] `:name` (String), `:was` (String, nil),
+      #   `:renames` (`Hash{String => String}`), `:moves`/`:converts`/`:retypes`/
+      #   `:computes`/`:rekeys`/`:backfills` (each an `Array<Hash>`), `:drops`
+      #   (`Array<String>`)
       def translation_aggregate(aggregate)
         {
           name:      aggregate.name,
@@ -137,30 +210,27 @@ module Hecks
           drops:     aggregate.drops.map(&:to_s),
           retypes:   aggregate.retypes.map { |retype| { from: retype.from, to: retype.to } },
           computes:  aggregate.computes.map { |compute| { from: compute.from, to: compute.to, sql: compute.sql } },
-          # PREVIOUSLY MISSING — found live while planning Rust-side mint
-          # support. An edge carrying only a rekey (no compute) had its
-          # approval bind to nothing rekey-specific at all: any two
-          # rekey edges with otherwise-identical renames/moves/converts/
-          # drops/retypes/computes produced the SAME digest regardless
-          # of what their `rekey sql:` actually said, and a rekey's own
-          # SQL could change without invalidating an existing approval.
-          # Same bug shape for `backfills` (present, just never
-          # exported). Fixing this CHANGES every existing rekey/
-          # backfill edge's digest — any approval already recorded for
-          # one is invalidated by this fix and must be re-reviewed.
+          # **`rekeys`/`backfills` are digest-relevant too.** Without them, an
+          # edge carrying only a rekey (no compute) would bind its approval
+          # to nothing rekey-specific: any two rekey edges with otherwise-
+          # identical renames/moves/converts/drops/retypes/computes would
+          # produce the same digest regardless of what their `rekey sql:`
+          # actually said, letting a rekey's own SQL change without
+          # invalidating an existing approval. Same reasoning covers
+          # `backfills`.
           rekeys:    aggregate.rekeys.map { |rekey| { sql: rekey.sql } },
           backfills: aggregate.backfills.map { |backfill| { name: backfill.name.to_s, default: backfill.default } }
         }
       end
 
-      # THE EXPORT SHAPE — `translation_aggregate`'s own digest-relevant
+      # The export shape — `translation_aggregate`'s own digest-relevant
       # fields, plus the precompiled SQL (`compiled_state_expression`/
       # `compiled_id_expression`) a consumer embedding this JSON
       # (rust/host's own boot-time mint) needs to execute the edge
-      # without compiling SQL itself. The SAME call head_compiler.rb's
+      # without compiling SQL itself. The same call head_compiler.rb's
       # own `compile_rules(declared)`/`id_case(guard, declared)` make at
       # mint time, run here once at build/export time instead —
-      # `Translation::RuleCompiler` is the ONE place this expression is
+      # `Translation::RuleCompiler` is the one place this expression is
       # built, called from both here and from head_compiler.rb's real
       # per-mint assembly, so a consumer gets Ruby's own compiler's
       # output verbatim, never a second, independently-authored SQL
@@ -176,6 +246,11 @@ module Hecks
       # declared-rules shape, just without precompiled SQL to execute —
       # consistent with there being no mint/audit machinery to run it
       # against either.
+      # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
+      #   translation rules to compile and export
+      # @return [Hash{Symbol => Object}] `translation_aggregate`'s own Hash, plus
+      #   `:compiled_state_expression` (String) and `:compiled_id_expression`
+      #   (String, nil) when the era persistence plugin is loaded
       def compiled_translation_aggregate(aggregate)
         return translation_aggregate(aggregate) unless Ports::Persistence.plugin?(:era)
 

data/lib/hecks/projector/ir_projector.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Projector
-    # The trivial case, on purpose: canonical IR projected AS canonical
+    # The trivial case, on purpose: canonical IR projected as canonical
     # IR. `Bluebook#to_h` already satisfies every §30 acceptance
     # criterion on its own — no live runtime needed to call it, output is
     # deterministic (the same golden fixtures `spec/ir_golden_spec.rb`
@@ -12,6 +12,12 @@ module Hecks
     module IRProjector
       module_function
 
+      # Projects `bluebook` as its own canonical IR.
+      #
+      # @param bluebook [Hecks::IR] the IR-emitting construct to project
+      # @param options [Hash] unused; accepted to satisfy the registry's call shape
+      # @return [Hash] `bluebook`'s canonical IR, as built by `Hecks::IR::Emits#to_h`
+      # @raise [Hecks::IR::Undeclared] if `bluebook` never declared its shape with `emits_ir`
       def call(bluebook:, options: {}) = bluebook.to_h
     end
   end