hecks 2.7.0 → 2.9.0

data/lib/hecks/projector/docs_projector.rb

@@ -2,65 +2,20 @@ require_relative "../naming"
 
 module Hecks
   module Projector
-    # 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
-    # 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.
-    #
-    # `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
-    # cannot drift from the domain either.
-    #
-    # ## 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.
-    # `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.
+    # Projects a bluebook as its own usage documentation, in Markdown.
+    # Reach it as `Projector.call(:docs, bluebook: ...)` or `Domain.docs`.
     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.
+      # Projects `bluebook` as Markdown usage documentation.
       #
       # @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
+      # @return [String] the document, ending in a newline
+      # @raise [Runtime::NotFound] if `options[:aggregate]` names no declared aggregate
       def call(bluebook:, options: {})
         depth = (options[:heading] || 1).to_i
         only  = options[:aggregate]
@@ -72,18 +27,7 @@ module Hecks
         "#{out.compact.join("\n").rstrip}\n"
       end
 
-      # 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
+      # An unknown aggregate name is refused rather than answered with an empty document.
       def aggregates(bluebook, only)
         return bluebook.aggregates unless only
 
@@ -93,25 +37,10 @@ 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
-        # 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
         out << "Previously known as `#{bluebook.formerly_known_as}`." if bluebook.formerly_known_as
@@ -121,22 +50,8 @@ 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
-      # 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 = []
 
@@ -165,14 +80,6 @@ module Hecks
         out.empty? ? nil : out.join("\n")
       end
 
-      # ── 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
@@ -192,18 +99,10 @@ 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
-        # own: its verb is spelled through the aggregate that holds it, and
-        # the parent's id travels alongside the entity's own identity.
+        # An entity has no door of its own; its verbs go through the holding aggregate.
         out << "Addressed through its holder — `#{aggregate.hecks_name}.#{entity.hecks_name}.<Verb>`, " \
                "passing the #{aggregate.hecks_name}'s `id` and this element's " \
                "`#{entity.identity_heads.join('`, `')}`."
@@ -215,14 +114,6 @@ module Hecks
         out.compact.join("\n")
       end
 
-      # ── 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?
@@ -233,15 +124,7 @@ module Hecks
         table(%w[attribute shape rules], rows)
       end
 
-      # 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
+      # A value object's fields, not its name: callers need to know what shape to send.
       def shape_of(attribute, holder)
         value_object = value_object_for(attribute, holder)
         inner =
@@ -254,12 +137,6 @@ 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 = []
@@ -273,25 +150,13 @@ 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?
 
         value_object.members.flat_map(&:values).uniq
       end
 
-      # 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
+      # An entity holds no value objects; its types are declared on the owning aggregate.
       def value_object_for(attribute, holder)
         scopes = [holder, holder.respond_to?(:hecks_owner) ? holder.hecks_owner : nil].compact
         scopes.each do |scope|
@@ -303,15 +168,6 @@ module Hecks
         nil
       end
 
-      # ── 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
 
@@ -323,15 +179,6 @@ module Hecks
          table(%w[verb from to], rows)].join("\n")
       end
 
-      # ── 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?
@@ -341,13 +188,6 @@ 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
@@ -371,15 +211,6 @@ module Hecks
         out.join("\n")
       end
 
-      # The argument table's own rows — a pure per-attribute mapping with
-      # 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)
@@ -387,15 +218,7 @@ module Hecks
         end
       end
 
-      # 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
+      # Refusals come from the lifecycle edge, the command's `given`s and reference resolution.
       def refusals_of(command, holder)
         refusals = []
 
@@ -416,14 +239,6 @@ module Hecks
         refusals + command.givens.map { |given| "not: #{given.description}" }
       end
 
-      # ── 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?
 
@@ -440,12 +255,6 @@ 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

@@ -3,13 +3,8 @@ require_relative "../ports/persistence"
 
 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
-    # (`translation_hash`, what ApprovalDigest hashes) and their
-    # 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.
+    # Registry-wide serialization to Hash/JSON, for the canonical bluebook IR,
+    # binding facts, and translation edges (declared and compiled).
     module Exporter
       module_function
 
@@ -29,27 +24,10 @@ module Hecks
         JSON.pretty_generate(call(registry))
       end
 
-      # 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
-      # 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
-      # way `translations` already sits beside `call`'s output rather than
-      # inside it.
+      # Whether each aggregate is bound to a lineage-capable adapter — a per-deployment
+      # binding fact, not part of the declared IR `call` exports (ADR 0001).
+      # Empty when the era persistence plugin isn't loaded, rather than raising.
       #
-      # Reuses `Runtime::EraCheck`'s own capability predicates rather than
-      # re-deriving them — the boot-time gate and this export must never
-      # answer differently for the same aggregate.
-      #
-      # ADR 0033 — `Runtime::EraCheck` lives in the (optional) era
-      # persistence plugin now; unloaded, this answers exactly what it
-      # 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`,
@@ -68,20 +46,9 @@ 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`),
-      # 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`
-      # (`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,
-      # LocalStorage — `rust/host` understands only Postgres/PostgresEra
-      # 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.
+      # Every aggregate's declared persistence adapter (`persisted_by`) — a binding
+      # fact like `lineage`, not part of the declared IR `call` exports (ADR 0001).
+      #
       # @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
@@ -99,13 +66,9 @@ module Hecks
         { aggregates: aggregates }
       end
 
-      # 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.
+      # Which chapter this domain's role checks resolve against
+      # (`Registry#authorization_provider_for`); `{}` if none does.
+      #
       # @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`
@@ -126,11 +89,9 @@ module Hecks
         }
       end
 
-      # Same seam as `authorization` — which chapter answers "who may
-      # sign in" (`Registry#membership_provider_for`), with its declared
-      # verbs qualified and the membership aggregate named off `admit`.
-      # rust/host reads this instead of HECKS_MEMBERSHIP_AGGREGATE.
-      # `{}` when nothing this domain attaches provides membership.
+      # Which chapter answers "who may sign in" (`Registry#membership_provider_for`),
+      # with the membership aggregate named off `admit`; `{}` if none does.
+      #
       # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
       # @param domain_name [String] the domain to export the membership binding for
       # @return [Hash{Symbol => String, nil}] `:provider` (name), `:admit`, `:grant`,
@@ -151,12 +112,9 @@ module Hecks
         }
       end
 
-      # Same seam as `authorization` — which chapter answers "who is this
-      # authenticated pair" (`Registry#identity_provider_for`), with its
-      # declared verbs qualified. rust/host reads this instead of naming
-      # Identity::Identity.Register / ExternalIdentifier.Link. `{}` when
-      # nothing this domain attaches provides identity. Breaking in 2.0:
-      # Link's reference field is `identity`, never `identity_id`.
+      # Which chapter answers "who is this authenticated pair"; `{}` if none does.
+      # Breaking in 2.0: Link's reference field is `identity`, never `identity_id`.
+      #
       # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
       # @param domain_name [String] the domain to export the identity binding for
       # @return [Hash{Symbol => String, nil}] `:provider` (name), `:register`, `:link`,
@@ -174,12 +132,9 @@ module Hecks
         }
       end
 
-      # Same seam as `membership` — which chapter answers the guest
-      # newsletter signup (`Registry#newsletter_provider_for`), with its
-      # declared verbs qualified and the subscribing aggregate named off
-      # `subscribe`. rust/host reads this instead of naming
-      # Newsletter::Subscriber.Subscribe and friends. `{}` when nothing
-      # this domain attaches provides newsletter.
+      # Which chapter answers the guest newsletter signup
+      # (`Registry#newsletter_provider_for`); `{}` if none does.
+      #
       # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
       # @param domain_name [String] the domain to export the newsletter binding for
       # @return [Hash{Symbol => String, nil}] `:provider` (name), `:subscribe`, `:add_name`,
@@ -203,11 +158,8 @@ module Hecks
       end
 
       # Which chapter answers sending a newsletter issue
-      # (`Registry#newsletter_issues_provider_for`), with its declared verbs
-      # qualified and the issue and delivery aggregates named off them.
-      # rust/host's send route reads this instead of naming
-      # Newsletter::Issue.Send and Newsletter::Delivery.Record. `{}` when
-      # nothing this domain attaches provides newsletter_issues.
+      # (`Registry#newsletter_issues_provider_for`); `{}` if none does.
+      #
       # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
       # @param domain_name [String] the domain to export the issue-sending binding for
       # @return [Hash{Symbol => String, nil}] `:provider` (name), `:send_issue`,
@@ -230,11 +182,9 @@ module Hecks
         }
       end
 
-      # Same seam as `newsletter` — which chapter answers scheduling sessions
-      # and taking registrations (`Registry#registrations_provider_for`), with
-      # its declared verbs qualified and the event and registration aggregates
-      # named off them. `{}` when nothing this domain attaches provides
-      # registrations.
+      # Which chapter answers scheduling sessions and taking registrations
+      # (`Registry#registrations_provider_for`); `{}` if none does.
+      #
       # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
       # @param domain_name [String] the domain to export the registrations binding for
       # @return [Hash{Symbol => String, nil}] `:provider` (name), `:schedule`, `:request`
@@ -258,15 +208,14 @@ module Hecks
       end
 
       # Which chapter owns the payment-processor connection
-      # (`Registry#payment_connection_provider_for`), with its declared verbs
-      # qualified and the connection aggregate named off `connect`. `{}` when
-      # nothing this domain attaches provides payment_connection.
+      # (`Registry#payment_connection_provider_for`); `{}` if none does.
+      #
       # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
       # @param domain_name [String] the domain to export the payment-connection binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), one qualified verb per contract key
-      #   (`:connect`, `:reconnect`, `:disconnect`, `:suspend`, `:resume`, `:enable`, `:disable`) and
-      #   `:aggregate` (`:connect`'s own leading qualified aggregate name); `{}` if nothing this
-      #   domain attaches provides payment_connection
+      # @return [Hash{Symbol => String, nil}] `:provider` (name), one qualified verb per
+      #   contract key (`:connect`, `:reconnect`, `:disconnect`, `:suspend`, `:resume`,
+      #   `:enable`, `:disable`) and `:aggregate` (`:connect`'s own leading qualified
+      #   aggregate name); `{}` if nothing this domain attaches provides payment_connection
       def payment_connection(registry, domain_name)
         provider = registry.payment_connection_provider_for(domain_name)
         return {} unless provider
@@ -276,12 +225,9 @@ module Hecks
         { provider: provider.name, **verbs, aggregate: verbs[:connect]&.split(".")&.first }
       end
 
-      # Same seam as `newsletter` — which chapter takes payments
-      # (`Registry#payments_provider_for`), with its declared verbs
-      # qualified and the paying aggregate named off `initiate`. rust/host
-      # reads this instead of naming Payments::Payment.Initiate and the
-      # PaymentGateway operations. `{}` when nothing this domain attaches
-      # provides payments.
+      # Which chapter takes payments (`Registry#payments_provider_for`);
+      # `{}` if none does.
+      #
       # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
       # @param domain_name [String] the domain to export the payments binding for
       # @return [Hash{Symbol => String, nil}] `:provider` (name), `:initiate`, `:succeeded`,
@@ -302,14 +248,9 @@ module Hecks
         }
       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
-      # (see that method's own header for why the two must stay
-      # 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.
+      # Every registered translation, with each aggregate's precompiled SQL attached —
+      # `values:` serializes as `[key, value]` pairs since 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
@@ -341,17 +282,9 @@ module Hecks
         JSON.pretty_generate(translations(registry))
       end
 
-      # 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
-      # 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
-      # emit from it.
+      # The digest-relevant shape `ApprovalDigest.edge_digest` hashes — declared rules only,
+      # never the compiled SQL, so a compiler-output change can't invalidate an approval.
+      #
       # @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`
@@ -386,42 +319,17 @@ 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 } },
-          # **`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`/`backfills` are digest-relevant too — a rekey with no compute
+          # would otherwise collide with any other, letting its SQL change silently
+          # invalidate nothing.
           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
-      # 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
-      # 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
-      # 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
-      # compiler that could drift from this one. `compiled_id_
-      # expression` is nil unless this edge rekeys — the bare
-      # `aggregate_id` passthrough head_compiler.rb itself falls back to
-      # for the overwhelming common case.
-      # ADR 0033 — `Translation::RuleCompiler` lives in the era plugin;
-      # unloaded, there is nothing that can compile this SQL, so this
-      # falls back to the bare declared fields (`translation_aggregate`
-      # alone) rather than raising on an undefined constant. A consumer
-      # embedding this JSON without the era plugin loaded gets the same
-      # declared-rules shape, just without precompiled SQL to execute —
-      # consistent with there being no mint/audit machinery to run it
-      # against either.
+      # `translation_aggregate`'s fields, plus precompiled SQL from the same
+      # `Translation::RuleCompiler` mint time uses (ADR 0033 governs its fallback).
+      #
       # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
       #   translation rules to compile and export
       # @return [Hash{Symbol => Object}] `translation_aggregate`'s own Hash, plus

data/lib/hecks/projector/ir_projector.rb

@@ -1,14 +1,7 @@
 module Hecks
   module Projector
-    # 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`
-    # pins), and target-version metadata rides along for free (`§7`'s
-    # `ir_version:` is the first key `to_h` emits). Registering it proves
-    # the framework's call shape against a real, already-load-bearing
-    # target before any genuinely new projector (`:rust`, `:ul`,
-    # `:openid`) has to.
+    # Projects a bluebook as its own canonical IR, via `Bluebook#to_h`.
+    # Needs no live runtime, and the output is deterministic.
     module IRProjector
       module_function