hecks 1.3.0 → 1.4.0

data/lib/hecks/projections/rust_vocabulary.rb

@@ -0,0 +1,443 @@
+require_relative "../projector"
+require_relative "../runtime/refusal_wording"
+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.
+    #
+    #   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
+
+      projects_as :rust_vocabulary, declares: "Vocabulary", emits: :files
+
+      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.
+      TABLES = {
+        "RefusalTemplate"        => { enum: "RefusalSite",     variant_from: %w[refusal site], file: "refusal_template",
+                                      kind: :templates, arguments: "RefusalSiteArgument" },
+        "QueryComparator"        => { enum: "QueryComparator", variant_from: %w[name], file: "query_comparator", kind: :set },
+        "FieldHint"              => { enum: "FieldHint",       variant_from: %w[name], file: "field_hint", kind: :set },
+        "AggregateDispatchOrder" => { enum: "AggregateStep",   variant_from: %w[step], file: "aggregate_dispatch_order",
+                                      kind: :order },
+        "EntityDispatchOrder"    => { enum: "EntityStep",      variant_from: %w[step], file: "entity_dispatch_order",
+                                      kind: :order }
+      }.freeze
+
+      RUST_KEYWORDS = %w[as async await break const continue crate dyn else enum extern false fn for if impl in let loop
+                         match mod move mut pub ref return self static struct super trait true type unsafe use where
+                         while abstract become box do final macro override priv typeof unsized virtual yield try].freeze
+
+      module_function
+
+      def call(bluebook:, options: {}) = render(bluebook)
+
+      def render(bluebook)
+        tables = Vocabulary.tables(bluebook)
+        files = TABLES.to_h do |table, spec|
+          rows = tables.fetch(table) { raise ArgumentError, "Vocabulary declares no #{table} table" }
+          arguments = spec[:arguments] && tables.fetch(spec[:arguments]) do
+            raise ArgumentError, "Vocabulary declares no #{spec[:arguments]} table"
+          end
+          ["vocab/#{spec[:file]}.rs", table_file(table, spec, rows, arguments)]
+        end
+        { "vocab/mod.rs" => mod_file }.merge(files)
+      end
+
+      def header(table)
+        <<~RUST
+          // GENERATED by #{GENERATOR} (Hecks::Projections::RustVocabulary,
+          // lib/hecks/projections/rust_vocabulary.rb) from Vocabulary::#{table}
+          // (#{SOURCE}).
+          // Do not hand-edit — re-run #{GENERATOR} instead.
+        RUST
+      end
+
+      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")
+        <<~RUST
+          // GENERATED by #{GENERATOR} (Hecks::Projections::RustVocabulary,
+          // lib/hecks/projections/rust_vocabulary.rb) from the Vocabulary
+          // aggregate (#{SOURCE}).
+          // Do not hand-edit — re-run #{GENERATOR} instead.
+          //
+          // One module per projected table. Every enum below is matched
+          // exhaustively by its own accessors — no wildcard arm — so a row the
+          // language gains fails to compile until it is handled.
+
+          #{mods}
+
+          #{exports}
+        RUST
+      end
+
+      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
+        raise ArgumentError, "duplicate #{spec[:enum]} variant(s): #{duplicates.join(', ')}" if duplicates.any?
+
+        enum   = spec[:enum]
+        fields = rows.first.keys
+        by_site = spec[:kind] == :templates ? site_arguments(rows, argument_rows) : nil
+        body = [
+          header(table),
+          "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]",
+          "pub enum #{enum} {",
+          variants.map { |variant| "    #{variant}," },
+          "}",
+          "",
+          "impl #{enum} {",
+          constants(enum, variants, spec[:kind]),
+          fields.map { |field| accessor(enum, field, variants, rows) },
+          from_name(enum, spec[:kind]),
+          extras(enum, variants, spec[:kind]),
+          "}",
+          "",
+          by_site ? argument_types(enum, variants, rows, by_site) : [],
+          tests(enum, spec[:kind], variants, rows, by_site)
+        ]
+        "#{body.flatten.join("\n").rstrip}\n"
+      end
+
+      def constants(enum, variants, kind)
+        list = variants.map { |variant| "        #{enum}::#{variant}," }
+        if kind == :order
+          ["    /// The declared step order, first to last.",
+           "    pub const ORDER: [#{enum}; #{variants.size}] = [", list, "    ];", ""]
+        else
+          ["    /// Every row, in declared order.",
+           "    pub const ALL: &'static [#{enum}] = &[", list, "    ];", ""]
+        end
+      end
+
+      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}`.",
+         "    pub fn #{accessor_name(field)}(&self) -> &'static str {",
+         "        match self {",
+         arms,
+         "        }",
+         "    }",
+         ""]
+      end
+
+      # Built on the enum's own list and name accessor, not a string
+      # match, so it needs no wildcard arm either.
+      def from_name(enum, kind)
+        list  = kind == :order ? "ORDER" : "ALL"
+        field = kind == :templates ? "site" : name_field(kind)
+        ["    /// The row whose `#{field}` is `name`, if any.",
+         "    pub fn from_name(name: &str) -> Option<#{enum}> {",
+         "        #{enum}::#{list}.iter().copied().find(|row| row.#{accessor_name(field)}() == name)",
+         "    }",
+         ""]
+      end
+
+      def extras(enum, variants, kind)
+        case kind
+        when :order
+          arms = variants.each_with_index.map { |variant, index| "            #{enum}::#{variant} => #{index}," }
+          ["    /// This step's index in `ORDER`.",
+           "    pub fn position(&self) -> usize {",
+           "        match self {",
+           arms,
+           "        }",
+           "    }"]
+        when :templates
+          ["    /// `RefusalWording.substitute`: replace every `{key}` marker, in the",
+           "    /// order given. A template is read, never evaluated. Private: call",
+           "    /// sites go through a site's typed `<Variant>Args::render_args`,",
+           "    /// which formats and supplies every declared argument.",
+           "    fn render(&self, values: &[(&str, &str)]) -> String {",
+           "        let mut text = self.template().to_string();",
+           "        for (key, value) in values {",
+           "            text = text.replace(&format!(\"{{{key}}}\"), value);",
+           "        }",
+           "        text",
+           "    }"]
+        else
+          []
+        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.
+      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")] }
+        raise ArgumentError, "RefusalSiteArgument rows name no RefusalTemplate: #{orphans.inspect}" if orphans.any?
+
+        rows.to_h do |row|
+          key   = [row.fetch("refusal"), row.fetch("site")]
+          specs = grouped.fetch(key, [])
+          wants = row.fetch("template").scan(/\{(\w+)\}/).flatten.uniq
+          names = specs.map { |spec| spec.fetch("argument") }
+          unless names == wants
+            raise ArgumentError, "RefusalSiteArgument for #{key.join('/')} declares #{names.inspect}; " \
+                                 "its template's placeholders are #{wants.inspect}"
+          end
+          specs.each { |spec| check_rule!(key, spec) }
+          [key, specs]
+        end
+      end
+
+      def check_rule!(key, spec)
+        where = "#{key.join('/')}.#{spec.fetch('argument')}"
+        unless Runtime::RefusalWording::SHAPES.include?(spec.fetch("shape"))
+          raise ArgumentError, "#{where}: unknown shape #{spec['shape'].inspect}"
+        end
+        unless Runtime::RefusalWording::QUOTINGS.include?(spec.fetch("quoting"))
+          raise ArgumentError, "#{where}: unknown quoting #{spec['quoting'].inspect}"
+        end
+        return if %w[true false].include?(spec.fetch("sorted"))
+
+        raise ArgumentError, "#{where}: sorted must be \"true\" or \"false\""
+      end
+
+      def argument_types(enum, variants, rows, by_site)
+        support = [
+          "/// Ruby's `#inspect` of a name, as a refusal quotes it: `{:?}` on a",
+          "/// `&str`, the quoting every kernel call site used before",
+          "/// RefusalSiteArgument existed.",
+          "fn quoted(text: &str) -> String {",
+          "    format!(\"{text:?}\")",
+          "}",
+          "",
+          "/// A list argument, written the way its RefusalSiteArgument row says:",
+          "/// sorted first (before quoting), each item quoted, then joined; an",
+          "/// empty list reads `when_empty`.",
+          "fn list(items: &[&str], sorted: bool, inspect: bool, separator: &str, when_empty: &str) -> String {",
+          "    let mut items = items.to_vec();",
+          "    if sorted {",
+          "        items.sort_unstable();",
+          "    }",
+          "    if items.is_empty() {",
+          "        return when_empty.to_string();",
+          "    }",
+          "    let write = |item: &&str| if inspect { quoted(item) } else { item.to_string() };",
+          "    items.iter().map(write).collect::<Vec<_>>().join(separator)",
+          "}",
+          ""
+        ]
+        support + variants.zip(rows).flat_map do |variant, row|
+          args_struct(enum, variant, row, by_site.fetch([row.fetch("refusal"), row.fetch("site")]))
+        end
+      end
+
+      def args_struct(enum, variant, row, specs)
+        fields = specs.flat_map do |spec|
+          type = spec.fetch("shape") == "list" ? "&'a [&'a str]" : "&'a str"
+          ["    /// #{rule_reading(spec)}", "    pub #{rust_field(spec.fetch('argument'))}: #{type},"]
+        end
+        locals = specs.filter_map { |spec| formatted_local(spec) }
+        pairs  = specs.map do |spec|
+          name  = spec.fetch("argument")
+          value = formatted_local(spec) ? "#{local_name(name)}.as_str()" : "self.#{rust_field(name)}"
+          "            (#{rust_string(name)}, #{value}),"
+        end
+        ["/// `#{enum}::#{variant}`'s arguments — `RefusalWording.render_site(" \
+         "#{rust_string(row.fetch('refusal'))}, #{rust_string(row.fetch('site'))}, ...)`.",
+         "#[derive(Debug, Clone, Copy)]",
+         "pub struct #{variant}Args<'a> {",
+         fields,
+         "}",
+         "",
+         "impl #{variant}Args<'_> {",
+         "    /// The site's wording, every argument formatted by its declared row.",
+         "    pub fn render_args(&self) -> String {",
+         locals.map { |line| "        #{line}" },
+         "        #{enum}::#{variant}.render(&[",
+         pairs,
+         "        ])",
+         "    }",
+         "}",
+         ""]
+      end
+
+      def formatted_local(spec)
+        name  = spec.fetch("argument")
+        field = "self.#{rust_field(name)}"
+        if spec.fetch("shape") == "list"
+          "let #{local_name(name)} = list(#{field}, #{spec.fetch('sorted')}, #{spec.fetch('quoting') == 'inspect'}, " \
+            "#{rust_string(spec.fetch('separator'))}, #{rust_string(spec.fetch('when_empty'))});"
+        elsif spec.fetch("quoting") == "inspect"
+          "let #{local_name(name)} = quoted(#{field});"
+        end
+      end
+
+      def rule_reading(spec)
+        quoting = spec.fetch("quoting") == "inspect" ? ", quoted" : ""
+        return "scalar#{quoting}" unless spec.fetch("shape") == "list"
+
+        sorted = spec.fetch("sorted") == "true" ? ", sorted" : ""
+        "list#{sorted}#{quoting}, joined #{spec.fetch('separator').inspect}, empty reads #{spec.fetch('when_empty').inspect}"
+      end
+
+      def local_name(argument) = "#{argument}_text"
+
+      def rust_field(argument) = RUST_KEYWORDS.include?(argument) ? "r##{argument}" : argument
+
+      def tests(enum, kind, variants = [], rows = [], by_site = nil)
+        list = kind == :order ? "ORDER" : "ALL"
+        name = accessor_name(kind == :templates ? "site" : name_field(kind))
+        lines = ["#[cfg(test)]",
+                 "mod tests {",
+                 "    use super::*;",
+                 ""]
+        unless kind == :templates
+          lines += ["    #[test]",
+                    "    fn every_row_is_found_by_its_own_name() {",
+                    "        for row in #{enum}::#{list}.iter() {",
+                    "            assert_eq!(#{enum}::from_name(row.#{name}()), Some(*row));",
+                    "        }",
+                    "    }",
+                    ""]
+        end
+        lines += order_test(enum) if kind == :order
+        if kind == :templates
+          lines += placeholder_test(enum)
+          lines += [""] + render_args_test(variants, rows, by_site)
+        end
+        lines.pop while lines.last == ""
+        lines + ["}"]
+      end
+
+      def order_test(enum)
+        ["    #[test]",
+         "    fn position_is_the_index_in_order() {",
+         "        for (index, step) in #{enum}::ORDER.iter().enumerate() {",
+         "            assert_eq!(step.position(), index);",
+         "        }",
+         "    }",
+         ""]
+      end
+
+      # 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() {",
+         "        for site in #{enum}::ALL {",
+         "            let template = site.template();",
+         "            let mut keys: Vec<String> = Vec::new();",
+         "            let mut current: Option<String> = None;",
+         "            for ch in template.chars() {",
+         "                match (ch, current.as_mut()) {",
+         "                    ('{', _) => current = Some(String::new()),",
+         "                    ('}', Some(key)) => {",
+         "                        keys.push(key.clone());",
+         "                        current = None;",
+         "                    }",
+         "                    (_, Some(key)) => key.push(ch),",
+         "                    (_, None) => {}",
+         "                }",
+         "            }",
+         "            let dummies: Vec<(String, String)> = keys.iter().map(|k| (k.clone(), format!(\"<{k}>\"))).collect();",
+         "            let pairs: Vec<(&str, &str)> = dummies.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();",
+         "            let rendered = site.render(&pairs);",
+         "            assert!(",
+         "                !rendered.contains('{') && !rendered.contains('}'),",
+         "                \"{site:?} left an unrendered placeholder behind: {rendered:?}\"",
+         "            );",
+         "        }",
+         "    }"]
+      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.
+      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")])
+          argument_cases(specs).map do |arguments|
+            expected = Runtime::RefusalWording.render_with(row.fetch("template"), specs, arguments)
+            fields = specs.map do |spec|
+              value = arguments.fetch(spec.fetch("argument").to_sym)
+              rust_value = value.is_a?(Array) ? "&[#{value.map { |item| rust_string(item) }.join(', ')}]" : rust_string(value)
+              "#{rust_field(spec.fetch('argument'))}: #{rust_value}"
+            end
+            ["        assert_eq!(",
+             "            #{variant}Args { #{fields.join(', ')} }.render_args(),",
+             "            #{rust_string(expected)}",
+             "        );"]
+          end
+        end
+        ["    #[test]",
+         "    fn render_args_matches_ruby_render_site() {",
+         asserts,
+         "    }"].flatten
+      end
+
+      LIST_CASES = [[], ["only \"one\""], %w[zeta alpha mid]].freeze
+
+      def argument_cases(specs)
+        cases = specs.any? { |spec| spec.fetch("shape") == "list" } ? LIST_CASES : [nil]
+        cases.map do |items|
+          specs.to_h do |spec|
+            name = spec.fetch("argument")
+            [name.to_sym, spec.fetch("shape") == "list" ? items : "#{name} \"x\""]
+          end
+        end
+      end
+
+      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.
+      def accessor_name(field) = field == "refusal" ? "refusal_class" : field
+
+      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/)
+
+        name
+      end
+
+      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.
+      def rust_string(text)
+        escaped = text.to_s.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("\n") { "\\n" }
+        "\"#{escaped}\""
+      end
+    end
+  end
+end

data/lib/hecks/projections/shape.rb

@@ -3,11 +3,11 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE STORAGE SHAPE of one bluebook — the same structural form
+    # 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`
+    # 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

data/lib/hecks/projections/statements.rb

@@ -2,7 +2,7 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # A DOMAIN'S OWN DECLARED FACTS, PROJECTED AS PLAIN ENGLISH SENTENCES
+    # 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,
@@ -10,25 +10,25 @@ module Hecks
     # a sanity check that the domain still says what someone thinks it
     # says).
     #
-    # NEVER INVENTS A SENTENCE FROM NOTHING — `DocsProjector`'s own
+    # **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,
+    # 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
+    # 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 THE SAME WAY EVERY PROJECTION ALREADY IS, no new facade
+    # Reachable the same way every projection already is, 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
+    # 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
@@ -50,7 +50,7 @@ module Hecks
         attribute_statements(holder) + invariant_statements(holder)
       end
 
-      # "MANY" READS THE SAME WAY REGARDLESS OF WHAT'S BEHIND IT — a
+      # "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
@@ -77,17 +77,17 @@ module Hecks
         end
       end
 
-      # "AN ACCOUNT", NOT "A ACCOUNT" — every subject/object noun here is
+      # "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.
+      # word starting with a consonant letter but a vowel sound.
       def article(word) = word.to_s.match?(/\A[AEIOUaeiou]/) ? "An" : "A"
 
-      # INVARIANTS LIVE IN TWO PLACES — directly on the holder (an
+      # 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.
@@ -97,7 +97,7 @@ module Hecks
         (own + nested).map { |invariant| invariant_statement(invariant) }
       end
 
-      # THE DOMAIN AUTHOR'S OWN WORDS, CAPITALIZED AND PUNCTUATED —
+      # 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.
       def invariant_statement(invariant)

data/lib/hecks/projections/vocabulary.rb

@@ -2,20 +2,20 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE CLOSED SETS, PROJECTED — lib/hecks/vocabulary.rb rendered
+    # **The closed sets, projected** — lib/hecks/vocabulary.rb rendered
     # from whichever chapter declares a `Vocabulary` aggregate, which in
     # practice is the language projecting its own tables.
     #
     #   Projector.call(:vocabulary, bluebook: <the Bluebook chapter>)
     #
-    # A PROJECTION RATHER THAN A BIN/ SCRIPT, and that correction is the
+    # A projection rather than a bin/ script, and that correction is the
     # point of it. This was first written as its own program with its own
     # call shape, beside `bin/project_parser_table`, `bin/reference` and
     # `bin/expression_projection` — four tools doing "canonical IR in,
     # external artifact out" four different ways, which is the exact
     # thing the projector registry exists to stop.
     #
-    # Reads the chapter's JUDGED IR, so what is written out is what the
+    # Reads the chapter's judged IR, so what is written out is what the
     # language actually holds rather than what a builder happened to
     # produce.
     module Vocabulary
@@ -24,10 +24,10 @@ module Hecks
       projects_as :vocabulary, declares: "Vocabulary"
 
       HEADER = <<~RUBY.freeze
-        # GENERATED — projected from the language's own Vocabulary aggregate
+        # Generated — projected from the language's own Vocabulary aggregate
         # (lib/hecks/language/bluebook/vocabulary.bluebook).
         #
-        # DO NOT EDIT. spec/vocabulary_table_spec.rb re-projects this in memory
+        # Do not edit. spec/vocabulary_table_spec.rb re-projects this in memory
         # and refuses a diff, so an edit here fails the ordinary suite.
         #
         # Plain data on purpose — no requires, no dependency on the model —
@@ -42,9 +42,9 @@ module Hecks
       # has nothing to vary.
       def call(bluebook:, options: {}) = render(bluebook)
 
-      # FULL ROWS, not just the first field of each.
+      # Full rows, not just the first field of each.
       #
-      # Most vocabularies ARE one-field lists and the field is the term.
+      # Most vocabularies are one-field lists and the field is the term.
       # Several are not: `Comparison` declares the algebra each operator
       # computes with, `RefusalTemplate` an error plus its key and text.
       # Taking the first field of those produced a list of thirty-nine
@@ -69,8 +69,8 @@ module Hecks
           #{rows.join(",\n")}
               }.freeze
 
-              # THE TERMS — the first field of each row, which for a
-              # one-field vocabulary is the whole of it. Derived ONCE and
+              # The terms — the first field of each row, which for a
+              # one-field vocabulary is the whole of it. Derived once and
               # frozen rather than mapped per call: these are constant
               # tables, and a constant that allocates a new array every
               # time it is read is not one.

data/lib/hecks/projections.rb

@@ -1,7 +1,7 @@
 require_relative "projector"
 
 module Hecks
-  # THE TARGETS A DOMAIN CAN BE PROJECTED INTO, as constants rather than
+  # The targets a domain can be projected into, as constants rather than
   # bare symbols — `Pizzas.project(Projections::OIDC)`.
   #
   # A constant is worth the namespace for two reasons a Symbol cannot
@@ -10,9 +10,9 @@ module Hecks
   # carry its own documentation and defaults.
   #
   # Namespaced rather than top-level because `IR` is already taken —
-  # `Hecks::Bluebook` is the MODEL (`Bluebook::Command`, and the
+  # `Hecks::Bluebook` is the model (`Bluebook::Command`, and the
   # chapter class itself).
-  # `Projections::IR` is the projection OF that model, a different thing
+  # `Projections::IR` is the projection of that model, a different thing
   # that would be genuinely confusing under the same bare name.
   #
   # `include Hecks::Projections` gets the short spelling where the
@@ -26,6 +26,8 @@ require_relative "projections/shape"
 require_relative "projections/oidc"
 require_relative "projections/vocabulary"
 require_relative "projections/parser_table"
+require_relative "projections/bootstrap_table"
+require_relative "projections/rust_vocabulary"
 require_relative "projections/reference"
 require_relative "projections/model"
 require_relative "projections/diagrams"