hecks 2.7.0 → 2.9.0

data/lib/hecks/projections/rust_vocabulary.rb

@@ -4,38 +4,11 @@ require_relative "vocabulary"
 
 module Hecks
   module Projections
-    # The language's closed sets, projected into the Rust kernel — one
-    # `rust/src/kernel/vocab/<table>.rs` per Vocabulary table, each a
-    # `pub enum` plus `match`-based accessors with no wildcard arm, so a
-    # row the chapter gains is a compile error at every exhaustive match
-    # over it rather than a silent gap.
+    # The language's closed sets as Rust enums, one `rust/src/kernel/vocab/<table>.rs` per table,
+    # matched with no wildcard arm so a new row fails to compile until it is handled.
     #
     #   Projector.call(:rust_vocabulary, bluebook: <the Bluebook chapter>)
     #   # => { "vocab/mod.rs" => "...", "vocab/refusal_template.rs" => "...", ... }
-    #
-    # Paths are relative to rust/src/kernel/; bin/project_rust_vocabulary
-    # writes them. This generalizes the old bin/project_refusal_wording,
-    # which read Runtime::RefusalWording::TEMPLATES — a hand-typed copy of
-    # the RefusalTemplate rows. This reads the chapter itself.
-    #
-    # ## Only `TABLES` the kernel needs
-    #
-    # Each entry in `TABLES` names its enum and its generated extras; a
-    # table not listed is not projected. The enum names that differ from
-    # the table name keep existing Rust call sites (`RefusalSite`) and the
-    # dispatch-step names D1 consumes (`AggregateStep`, `EntityStep`).
-    #
-    # ## Typed refusal arguments
-    #
-    # The templates table also reads RefusalSiteArgument: every site gets a
-    # `<Variant>Args` struct whose fields are exactly the site's declared
-    # arguments (a `&str` per scalar, a `&[&str]` per list) and a
-    # `render_args` that formats each one by its row. `render` itself stays
-    # private to the generated module, so no call site can pass an argument
-    # list by hand — leaving one out does not compile. The generated test
-    # pins every site's `render_args` output (empty, single and multiple
-    # unsorted lists) against Runtime::RefusalWording.render_with, computed
-    # here in Ruby.
     module RustVocabulary
       extend Projector::Target
 
@@ -44,10 +17,8 @@ module Hecks
       GENERATOR = "bin/project_rust_vocabulary".freeze
       SOURCE    = "lib/hecks/language/bluebook/vocabulary.bluebook".freeze
 
-      # table name => enum name, variant-naming fields, file stem, kind.
-      # `:order` tables also get `ORDER` and `position`; `:templates`
-      # gets `render`, the typed `<Variant>Args` (read off the `arguments`
-      # table) and the placeholder and argument-rendering tests.
+      # Table name => enum name, variant-naming fields, file stem and kind.
+      # `:order` adds `position`; `:templates` adds `render` and the typed `<Variant>Args`.
       TABLES = {
         "RefusalTemplate"        => { enum: "RefusalSite",     variant_from: %w[refusal site], file: "refusal_template",
                                       kind: :templates, arguments: "RefusalSiteArgument" },
@@ -65,24 +36,8 @@ module Hecks
 
       module_function
 
-      # The projector protocol.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
-      #   Vocabulary aggregate to project
-      # @param options [Hash] unused; accepted to satisfy the registry's call shape
-      # @return [Hash{String => String}] each generated file's path, relative to
-      #   `rust/src/kernel/`, mapped to its full Rust source
       def call(bluebook:, options: {}) = render(bluebook)
 
-      # Renders every file `TABLES` projects: `vocab/mod.rs` plus one `.rs` file
-      # per table, each an exhaustive enum with accessors and a pinned test module.
-      #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
-      #   Vocabulary aggregate to render
-      # @return [Hash{String => String}] each generated file's path, relative to
-      #   `rust/src/kernel/`, mapped to its full Rust source
-      # @raise [ArgumentError] if `bluebook` does not declare a `TABLES`-named table,
-      #   or the `:arguments` table a `:templates` entry names
       def render(bluebook)
         tables = Vocabulary.tables(bluebook)
         files = TABLES.to_h do |table, spec|
@@ -95,11 +50,6 @@ module Hecks
         { "vocab/mod.rs" => mod_file }.merge(files)
       end
 
-      # The generated-file banner every projected file opens with.
-      #
-      # @param table [String] the Vocabulary table name being projected, such as
-      #   `"RefusalTemplate"`
-      # @return [String] the banner, as Rust line comments
       def header(table)
         <<~RUST
           // GENERATED by #{GENERATOR} (Hecks::Projections::RustVocabulary,
@@ -109,10 +59,6 @@ module Hecks
         RUST
       end
 
-      # Renders `vocab/mod.rs`, the entry point that re-exports every projected enum.
-      #
-      # @return [String] `vocab/mod.rs`'s full source: one `pub mod` and `pub use`
-      #   per entry in `TABLES`
       def mod_file
         mods    = TABLES.values.map { |spec| "pub mod #{spec[:file]};" }.join("\n")
         exports = TABLES.values.map { |spec| "pub use #{spec[:file]}::#{spec[:enum]};" }.join("\n")
@@ -132,18 +78,6 @@ module Hecks
         RUST
       end
 
-      # One table's full `.rs` source: its exhaustive enum, per-field accessors,
-      # `from_name`, its `:order`/`:templates` extras, and its `#[cfg(test)]` module.
-      #
-      # @param table [String] the Vocabulary table name, such as `"RefusalTemplate"`
-      # @param spec [Hash] the table's `TABLES` entry (`:enum`, `:variant_from`,
-      #   `:file`, `:kind`, and, for `:templates`, `:arguments`)
-      # @param rows [Array<Hash{String => String}>] the table's rows, as read off
-      #   the chapter by `Vocabulary.tables`
-      # @param argument_rows [Array<Hash{String => String}>, nil] the
-      #   `RefusalSiteArgument` rows, only when `spec[:kind] == :templates`
-      # @return [String] the table's full `.rs` file source
-      # @raise [ArgumentError] if two rows would generate the same enum variant name
       def table_file(table, spec, rows, argument_rows = nil)
         variants = rows.map { |row| variant_name(row, spec[:variant_from]) }
         duplicates = variants.tally.select { |_, count| count > 1 }.keys
@@ -172,14 +106,6 @@ module Hecks
         "#{body.flatten.join("\n").rstrip}\n"
       end
 
-      # Renders the enum's declared-order constant: `ORDER` for `:order`, `ALL` otherwise.
-      #
-      # @param enum [String] the Rust enum name, such as `"RefusalSite"`
-      # @param variants [Array<String>] each row's generated variant name, in
-      #   declared order
-      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
-      # @return [Array<String>] the lines declaring the enum's `ORDER` constant
-      #   (`:order`) or `ALL` constant (otherwise)
       def constants(enum, variants, kind)
         list = variants.map { |variant| "        #{enum}::#{variant}," }
         if kind == :order
@@ -191,16 +117,6 @@ module Hecks
         end
       end
 
-      # Renders one field's `pub fn` accessor, an exhaustive match over every variant.
-      #
-      # @param enum [String] the Rust enum name
-      # @param field [String] the row field this accessor reads, such as `"name"`
-      # @param variants [Array<String>] each row's generated variant name, in
-      #   declared order, matching `rows`
-      # @param rows [Array<Hash{String => String}>] the table's rows, in the same
-      #   order as `variants`
-      # @return [Array<String>] the lines for the field's `pub fn` accessor, one
-      #   match arm per variant
       def accessor(enum, field, variants, rows)
         arms = variants.zip(rows).map { |variant, row| "            #{enum}::#{variant} => #{rust_string(row.fetch(field))}," }
         ["    /// The row's declared `#{field}`.",
@@ -212,12 +128,7 @@ module Hecks
          ""]
       end
 
-      # Built on the enum's own list and name accessor, not a string
-      # match, so it needs no wildcard arm either.
-      #
-      # @param enum [String] the Rust enum name
-      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
-      # @return [Array<String>] the lines for the enum's `from_name` associated function
+      # Built on the enum's own list and name accessor, not a string match, so no wildcard arm.
       def from_name(enum, kind)
         list  = kind == :order ? "ORDER" : "ALL"
         field = kind == :templates ? "site" : name_field(kind)
@@ -228,14 +139,6 @@ module Hecks
          ""]
       end
 
-      # Renders the extra methods a table's `:kind` adds beyond the shared accessors.
-      #
-      # @param enum [String] the Rust enum name
-      # @param variants [Array<String>] each row's generated variant name, in
-      #   declared order
-      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
-      # @return [Array<String>] `:order`'s `position` method, `:templates`'s private
-      #   `render` method, or `[]` for `:set`
       def extras(enum, variants, kind)
         case kind
         when :order
@@ -263,20 +166,8 @@ module Hecks
         end
       end
 
-      # [refusal, site] => that site's argument rows, in declared order —
-      # refused unless they name exactly the template's own placeholders,
-      # in the order each first appears, with only known formatting rules.
-      #
-      # @param rows [Array<Hash{String => String}>] the `RefusalTemplate` rows,
-      #   in declared order
-      # @param argument_rows [Array<Hash{String => String}>] the `RefusalSiteArgument`
-      #   rows for every site
-      # @return [Hash{Array<String> => Array<Hash{String => String}>}] each
-      #   `[refusal, site]` pair mapped to its declared argument rows, in declared order
-      # @raise [ArgumentError] if an argument row names a `refusal`/`site` no
-      #   `RefusalTemplate` row declares, if a site's declared arguments do not match
-      #   its template's `{placeholder}`s in order, or if `check_rule!` rejects a
-      #   row's `"shape"`, `"quoting"`, or `"sorted"` value
+      # [refusal, site] => that site's argument rows; refused unless they name exactly the
+      # template's placeholders, in first-appearance order, with known formatting rules.
       def site_arguments(rows, argument_rows)
         grouped = argument_rows.group_by { |row| [row.fetch("refusal"), row.fetch("site")] }
         orphans = grouped.keys - rows.map { |row| [row.fetch("refusal"), row.fetch("site")] }
@@ -296,18 +187,6 @@ module Hecks
         end
       end
 
-      # Refuses a `RefusalSiteArgument` row whose formatting fields are not
-      # recognized rules.
-      #
-      # @param key [Array<String>] the `[refusal, site]` pair `spec` belongs to,
-      #   used in the raised message
-      # @param spec [Hash{String => String}] one `RefusalSiteArgument` row
-      #   (`"shape"`, `"quoting"`, `"sorted"`)
-      # @return [void]
-      # @raise [ArgumentError] if `spec`'s `"shape"` is not in
-      #   `Runtime::RefusalWording::SHAPES`, its `"quoting"` is not in
-      #   `Runtime::RefusalWording::QUOTINGS`, or its `"sorted"` is not
-      #   `"true"`/`"false"`
       def check_rule!(key, spec)
         where = "#{key.join('/')}.#{spec.fetch('argument')}"
         unless Runtime::RefusalWording::SHAPES.include?(spec.fetch("shape"))
@@ -321,17 +200,6 @@ module Hecks
         raise ArgumentError, "#{where}: sorted must be \"true\" or \"false\""
       end
 
-      # Renders every `:templates` variant's typed argument struct, plus the two
-      # helper functions (`quoted`, `list`) they share.
-      #
-      # @param enum [String] the Rust enum name
-      # @param variants [Array<String>] each row's generated variant name, matching `rows`
-      # @param rows [Array<Hash{String => String}>] the `RefusalTemplate` rows, in
-      #   the same order as `variants`
-      # @param by_site [Hash{Array<String> => Array<Hash{String => String}>}] each
-      #   `[refusal, site]` pair's declared argument rows, as built by `site_arguments`
-      # @return [Array<String>] the shared `quoted`/`list` helper functions, followed
-      #   by every variant's `<Variant>Args` struct and `render_args` implementation
       def argument_types(enum, variants, rows, by_site)
         support = [
           "/// Ruby's `#inspect` of a name, as a refusal quotes it: `{:?}` on a",
@@ -362,15 +230,6 @@ module Hecks
         end
       end
 
-      # Renders one variant's `<Variant>Args` struct and its `render_args` method.
-      #
-      # @param enum [String] the Rust enum name
-      # @param variant [String] the row's generated variant name
-      # @param row [Hash{String => String}] the `RefusalTemplate` row this variant projects
-      # @param specs [Array<Hash{String => String}>] the variant's declared
-      #   `RefusalSiteArgument` rows, in declared order
-      # @return [Array<String>] the lines for the variant's `<Variant>Args` struct
-      #   and its `render_args` method
       def args_struct(enum, variant, row, specs)
         fields = specs.flat_map do |spec|
           type = spec.fetch("shape") == "list" ? "&'a [&'a str]" : "&'a str"
@@ -401,15 +260,6 @@ module Hecks
          ""]
       end
 
-      # The `let` binding, if any, `args_struct` inserts before a variant's
-      # `render_args` computes its argument pairs.
-      #
-      # @param spec [Hash{String => String}] one `RefusalSiteArgument` row
-      #   (`"argument"`, `"shape"`, `"quoting"`, and, for a list, `"sorted"`,
-      #   `"separator"`, `"when_empty"`)
-      # @return [String, nil] the `let` line formatting the argument through
-      #   `list`/`quoted`, or `nil` if the argument needs no formatting local
-      #   (a scalar written as-is)
       def formatted_local(spec)
         name  = spec.fetch("argument")
         field = "self.#{rust_field(name)}"
@@ -421,13 +271,6 @@ module Hecks
         end
       end
 
-      # Describes one argument's formatting rule in English, for its struct field's doc comment.
-      #
-      # @param spec [Hash{String => String}] one `RefusalSiteArgument` row
-      #   (`"shape"`, `"quoting"`, and, for a list, `"sorted"`, `"separator"`,
-      #   `"when_empty"`)
-      # @return [String] a short English reading of the row's formatting rule,
-      #   used as the struct field's own doc comment
       def rule_reading(spec)
         quoting = spec.fetch("quoting") == "inspect" ? ", quoted" : ""
         return "scalar#{quoting}" unless spec.fetch("shape") == "list"
@@ -436,33 +279,10 @@ module Hecks
         "list#{sorted}#{quoting}, joined #{spec.fetch('separator').inspect}, empty reads #{spec.fetch('when_empty').inspect}"
       end
 
-      # The local variable name `formatted_local` binds an argument's formatted value to.
-      #
-      # @param argument [String] the `RefusalSiteArgument` row's `"argument"` name
-      # @return [String] the Rust local variable name `formatted_local` binds the
-      #   formatted value to
       def local_name(argument) = "#{argument}_text"
 
-      # An argument name, escaped for use as a Rust field/parameter identifier.
-      #
-      # @param argument [String] the `RefusalSiteArgument` row's `"argument"` name
-      # @return [String] `argument`, prefixed with `r#` if it collides with a Rust
-      #   keyword in `RUST_KEYWORDS`
       def rust_field(argument) = RUST_KEYWORDS.include?(argument) ? "r##{argument}" : argument
 
-      # Renders the table's `#[cfg(test)]` module: every kind's `from_name` round-trip
-      # test, plus `:order`'s and `:templates`' own tests.
-      #
-      # @param enum [String] the Rust enum name
-      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
-      # @param variants [Array<String>] each row's generated variant name, only
-      #   read when `kind == :templates`
-      # @param rows [Array<Hash{String => String}>] the table's rows, only read
-      #   when `kind == :templates`
-      # @param by_site [Hash{Array<String> => Array<Hash{String => String}>}, nil]
-      #   each `[refusal, site]` pair's declared argument rows, only read when
-      #   `kind == :templates`
-      # @return [Array<String>] the `#[cfg(test)]` module's full source lines
       def tests(enum, kind, variants = [], rows = [], by_site = nil)
         list = kind == :order ? "ORDER" : "ALL"
         name = accessor_name(kind == :templates ? "site" : name_field(kind))
@@ -488,11 +308,6 @@ module Hecks
         lines + ["}"]
       end
 
-      # The `:order` kind's own test, checked into every order table's test module.
-      #
-      # @param enum [String] the Rust enum name
-      # @return [Array<String>] the test asserting `ORDER`'s index matches each
-      #   variant's `position`
       def order_test(enum)
         ["    #[test]",
          "    fn position_is_the_index_in_order() {",
@@ -503,12 +318,7 @@ module Hecks
          ""]
       end
 
-      # Placeholders are read off each template's own text, never a second
-      # hand-kept list.
-      #
-      # @param enum [String] the Rust enum name
-      # @return [Array<String>] the test asserting every site's `render` leaves
-      #   no `{...}` placeholder unfilled
+      # Placeholders are read off each template's own text, never a second hand-kept list.
       def placeholder_test(enum)
         ["    #[test]",
          "    fn every_site_renders_with_no_leftover_placeholder() {",
@@ -538,21 +348,8 @@ module Hecks
          "    }"]
       end
 
-      # The Ruby oracle, pinned. Every site renders through its typed
-      # `render_args` for each edge case a list argument has — empty, one
-      # item, several out of order — and must equal what
-      # Runtime::RefusalWording.render_with answers for the same values,
-      # computed here at generation time. Scalars carry a `"` so quoting
-      # is compared too.
-      #
-      # @param variants [Array<String>] each row's generated variant name, matching `rows`
-      # @param rows [Array<Hash{String => String}>] the `RefusalTemplate` rows, in
-      #   the same order as `variants`
-      # @param by_site [Hash{Array<String> => Array<Hash{String => String}>}] each
-      #   `[refusal, site]` pair's declared argument rows, as built by `site_arguments`
-      # @return [Array<String>] the test asserting every variant's `render_args`
-      #   output for each `argument_cases` case matches
-      #   `Runtime::RefusalWording.render_with`, computed here in Ruby
+      # Pins each site's typed `render_args` to Runtime::RefusalWording.render_with, computed here,
+      # for empty, single and unsorted list arguments; scalars carry a `"` to compare quoting.
       def render_args_test(variants, rows, by_site)
         asserts = variants.zip(rows).flat_map do |variant, row|
           specs = by_site.fetch([row.fetch("refusal"), row.fetch("site")])
@@ -577,14 +374,6 @@ module Hecks
 
       LIST_CASES = [[], ["only \"one\""], %w[zeta alpha mid]].freeze
 
-      # Builds the argument-value cases `render_args_test` checks a site's
-      # `render_args` against.
-      #
-      # @param specs [Array<Hash{String => String}>] one site's declared
-      #   `RefusalSiteArgument` rows
-      # @return [Array<Hash{Symbol => Object}>] one argument Hash per test case —
-      #   `LIST_CASES` (empty, one item, several unsorted) if any spec is
-      #   list-shaped, else a single scalar case, each scalar value carrying a `"`
       def argument_cases(specs)
         cases = specs.any? { |spec| spec.fetch("shape") == "list" } ? LIST_CASES : [nil]
         cases.map do |items|
@@ -595,29 +384,11 @@ module Hecks
         end
       end
 
-      # The row field a table's `from_name`/round-trip test treats as its "name".
-      #
-      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
-      # @return [String] the row field used as this kind's "name" — `"step"` for
-      #   `:order`, `"name"` otherwise
       def name_field(kind) = kind == :order ? "step" : "name"
 
-      # `refusal` is a Rust-safe word but reads ambiguously beside the
-      # kernel's own `Refusal` enum; the accessor says what it answers.
-      #
-      # @param field [String] a row field name, such as `"name"` or `"refusal"`
-      # @return [String] the Rust accessor method name for `field` —
-      #   `"refusal_class"` for `"refusal"`, `field` otherwise
+      # `refusal` reads ambiguously beside the kernel's own `Refusal` enum.
       def accessor_name(field) = field == "refusal" ? "refusal_class" : field
 
-      # Builds one row's Rust enum variant name from its declared `variant_from` fields.
-      #
-      # @param row [Hash{String => String}] the table row to name
-      # @param fields [Array<String>] the row fields, PascalCased and concatenated
-      #   in order to build the variant name
-      # @return [String] the row's generated Rust enum variant name
-      # @raise [ArgumentError] if the built name is not a valid Rust variant
-      #   identifier (uppercase first letter, alphanumeric only)
       def variant_name(row, fields)
         name = fields.map { |field| pascal(row.fetch(field)) }.join
         raise ArgumentError, "#{name.inspect} is not a Rust variant name" unless name.match?(/\A[A-Z][A-Za-z0-9]*\z/)
@@ -625,18 +396,9 @@ module Hecks
         name
       end
 
-      # PascalCases one field value for use inside a generated variant name.
-      #
-      # @param text [String, Symbol, nil] the value to PascalCase; each
-      #   `_`-separated part's first letter is upcased
-      # @return [String] `text` converted to PascalCase, or `""` if `text` is `nil`
       def pascal(text) = text.to_s.split("_").map { |part| part[0].to_s.upcase + part[1..].to_s }.join
 
-      # A Rust string literal: only `\`, `"` and newlines need escaping in
-      # the text any vocabulary row holds.
-      #
-      # @param text [String] the value to render as a Rust string literal
-      # @return [String] `text`, backslash/quote/newline-escaped and wrapped in `"..."`
+      # Only `\`, `"` and newlines need escaping in the text a vocabulary row holds.
       def rust_string(text)
         escaped = text.to_s.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("\n") { "\\n" }
         "\"#{escaped}\""

data/lib/hecks/projections/shape.rb

@@ -3,21 +3,8 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # The storage shape of one bluebook — the same structural form
-    # `StorageShape.mint_hash` hashes to name an era, which is what makes
-    # a bump/no-bump question answerable by diffing two of these.
-    #
-    # The retrofit, and the point of it: `Runtime::StorageShape.project`
-    # was written long before this framework existed, and it already
-    # takes exactly one bluebook, already returns a plain Hash, already
-    # touches no disk and no live runtime — it even already uses the
-    # word. Nothing about it was shaped to fit `call(bluebook:, options:)`.
-    #
-    # That it fits anyway, by a two-line keyword adapter and no change to
-    # `StorageShape` itself, is the evidence that the protocol is a real
-    # description of what projections do here rather than a shape fitted
-    # around its own first example (`:ir`, whose `call` is `to_h`, proves
-    # much less on its own).
+    # The storage shape of one bluebook, the form `StorageShape.mint_hash` hashes to name an era.
+    # Diffing two of these answers whether a change bumps the era.
     module Shape
       extend Projector::Target
 
@@ -25,20 +12,7 @@ module Hecks
 
       module_function
 
-      # ADR 0033 — `Runtime::StorageShape` lives in the era persistence
-      # plugin now; the `:shape` projection itself stays registered
-      # unconditionally (the seam `spec/projector_seam_spec.rb` enforces
-      # is "every file here registers," not "every projection always
-      # succeeds") but refuses clearly if asked to run with the plugin
-      # unloaded, rather than raising on an undefined constant.
-      # Projects the storage shape of `bluebook` — the structural form an era
-      # bump/no-bump question is answered by diffing.
-      #
-      # @param bluebook [Bluebook::Chapter] the bluebook to reduce to its storage shape
-      # @param options [Hash] unused; accepted to satisfy the registry's call shape
-      # @return [Hash{String => Object}] `Runtime::StorageShape.project`'s Hash: `"name"`
-      #   and a sorted `"aggregates"` array
-      # @raise [RuntimeError] if the era persistence plugin is not loaded
+      # Registered even when the era plugin is unloaded; the call then refuses clearly.
       def call(bluebook:, options: {})
         unless Ports::Persistence.plugin?(:era)
           raise "the :shape projection needs the era persistence plugin loaded " \

data/lib/hecks/projections/statements.rb

@@ -2,40 +2,10 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # A domain's own declared facts, projected as plain english sentences
-    # — one atomic, independently-checkable statement per fact, not a
-    # flowing document (`Projections::Reference`/`DocsProjector` already
-    # do that job well; this is a flat list a caller can iterate, diff,
-    # or hand to something else entirely — a review, a test-plan seed,
-    # a sanity check that the domain still says what someone thinks it
-    # says).
+    # A domain's declared facts as flat plain-English sentences, one checkable statement per fact.
+    # Never invents one: relationships read from shape, invariants use the author's description.
     #
-    # ## Never invents a sentence from nothing
-    #
-    # `DocsProjector`'s own discipline, held here too: a relationship's
-    # sentence is built mechanically from its own declared shape (holder,
-    # target, relationship kind — the same facts `Projections::Diagrams`'s
-    # own relationship_edge already reads), and an invariant's sentence is
-    # the domain author's own `description`, capitalized and punctuated,
-    # never paraphrased. If a fact has no author-written description and
-    # no unambiguous mechanical phrasing, it doesn't get a sentence here —
-    # a wrong sentence is worse than a missing one.
-    #
-    # ## Reachable like any projection
-    #
-    # No new facade wiring needed: `Pizzas.project(Projections::Statements)`
-    # — `Facade::Surface::Chapter#project`'s own comment already settled
-    # this ("anything genuinely needing the graph is a projector, and a
-    # projector is given it"). `bin/statements` is a thin, optional
-    # convenience for reaching the same call from a shell.
-    #
-    # ## MVP scope
-    #
-    # "has many"/"has a"/"belongs to"/"references" sentences for every
-    # list or relationship attribute, and every invariant's own
-    # description (aggregate-level and every nested value object's),
-    # verbatim. Lifecycle transitions and command given/ensures read the
-    # same way and are the natural next sentences — not built yet.
+    #   Pizzas.project(Projections::Statements) # => ["A Pizza has many toppings.", ...]
     module Statements
       extend Hecks::Projector::Target
 
@@ -54,51 +24,17 @@ module Hecks
         holders(bluebook).flat_map { |holder| statements_for(holder) }
       end
 
-      # Every construct that can carry its own attributes and invariants — an
-      # aggregate and each of its entities.
-      #
-      # @param bluebook [Bluebook::Chapter] the chapter being walked
-      # @return [Array<Bluebook::Aggregate, Bluebook::Entity>] every aggregate followed
-      #   by its own entities, in declaration order
       def holders(bluebook) = bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
 
-      # All of one holder's sentences: its attribute relationships, then its invariants.
-      #
-      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct being
-      #   projected
-      # @return [Array<String>] the holder's sentences
       def statements_for(holder)
         attribute_statements(holder) + invariant_statements(holder)
       end
 
-      # "MANY" reads the same way regardless of what's behind it — a
-      # `has_many` relationship to another aggregate and a plain
-      # `list_of(Topping)` value-object attribute are the same idea to
-      # someone reading the domain in English ("an Order has many
-      # toppings" is true either way), even though they're two
-      # different IR shapes (a `Reference` versus an ordinary type).
-      # `attribute.name` carries the noun, not the target's own class
-      # name, because the field's own name is what the domain author
-      # actually chose to call the collection — "toppings", not
-      # "Topping".
-      # Projects every one of a holder's attributes that says something in plain
-      # English — a list, or a named relationship.
-      #
-      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct whose
-      #   attributes are being read
-      # @return [Array<String>] one sentence per list or relationship attribute; a
-      #   plain scalar attribute contributes none
+      # `has_many` and `list_of` read the same in English; `attribute.name` is the author's noun.
       def attribute_statements(holder)
         holder.attributes.filter_map { |attribute| attribute_statement(holder, attribute) }
       end
 
-      # Projects one attribute's relationship, if it has one worth stating.
-      #
-      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the attribute's owning
-      #   construct, named as the sentence's subject
-      # @param attribute [Bluebook::Attribute] the attribute being projected
-      # @return [String, nil] the sentence, or `nil` if `attribute` is neither a list
-      #   nor a `has_one`/`belongs_to`/`reference_to` relationship
       def attribute_statement(holder, attribute)
         subject = "#{article(holder.hecks_name)} #{holder.hecks_name}"
         return "#{subject} has many #{attribute.name}." if attribute.list?
@@ -112,24 +48,12 @@ module Hecks
         end
       end
 
-      # "An account", not "A ACCOUNT" — every subject/object noun here is
-      # a bare construct name (`ATMCard`, `ExternalTransfer`, `Account`),
-      # never free text, so the ordinary "starts with a vowel LETTER"
-      # heuristic is safe: this language's own naming never produces the
-      # English exceptions that heuristic gets wrong (an "hour", a
-      # "university") because a construct name is always spelled as a
-      # plain word, never an abbreviation read letter-by-letter or a
-      # word starting with a consonant letter but a vowel sound.
-      #
+      # Vowel-letter heuristic is safe: construct names are plain words, never initialisms.
       # @param word [String] a construct name to prefix
       # @return [String] `"An"` if `word` starts with a vowel letter, `"A"` otherwise
       def article(word) = word.to_s.match?(/\A[AEIOUaeiou]/) ? "An" : "A"
 
-      # Invariants live in two places — directly on the holder (an
-      # aggregate-level rule, checked after every command) and on every
-      # value object nested inside it — `DocsProjector#rules_of`'s own
-      # `value_object_for` lookup is the precedent for walking both.
-      #
+      # Invariants sit on the holder and on each nested value object; both are read.
       # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct whose
       #   invariants, and whose value objects' invariants, are being read
       # @return [Array<String>] one sentence per invariant, the holder's own first,
@@ -140,10 +64,7 @@ module Hecks
         (own + nested).map { |invariant| invariant_statement(invariant) }
       end
 
-      # The domain author's own words, capitalized and punctuated —
-      # nothing else. `invariant("a pizza is named")` already reads as
-      # a sentence; this is the entire transformation.
-      #
+      # The author's own description, capitalized and punctuated; no other transformation.
       # @param invariant [Bluebook::Invariant] the invariant being projected
       # @return [String] the invariant's `description`, capitalized, ending with `.`,
       #   `!` or `?`