hecks 5.0.0 → 6.0.0

data/lib/hecks/ports/persistence/plugins/era/translation/rule_compiler.rb

@@ -4,10 +4,29 @@ require_relative "expression_sql"
 module Hecks
   module Translation
     # Compiles one TranslationAggregate's declared rules into a jsonb-transforming SQL
-    # expression, shared by Ruby's own mint path and any other SQL-emitting caller.
+    # expression, shared by Ruby's own mint path and any other SQL-emitting caller. Each rule's
+    # Postgres form is a template read from the translation execution ledger
+    # (`lib/hecks/grammar/translation_rules.json`); this module only fills its holes.
     module RuleCompiler
       module_function
 
+      # Every admitted rule kind's Postgres template, read once from the replayed ledger.
+      #
+      # @return [Hash{String => String}] rule kind to its template, with `%{name}` holes
+      def postgres_forms
+        @postgres_forms ||= begin
+          require "hecks/grammar"
+          Grammar.rule_executions("postgres").freeze
+        end
+      end
+
+      # Fills one rule kind's Postgres template.
+      #
+      # @param kind [String] the rule kind, such as `"rename"`
+      # @param holes [Hash{Symbol => String}] the SQL each `%{name}` hole takes
+      # @return [String] the filled SQL
+      def form(kind, **holes) = format(postgres_forms.fetch(kind), **holes)
+
       # Compiles one edge's derive/rename/move/convert/drop/backfill rules into a nested
       # SQL expression over `state`, composed innermost-first in that phase order.
       def compile_rules(declared)
@@ -29,11 +48,8 @@ module Hecks
       # Wraps `expression` so a derive's text lands at its destination when the expression has a
       # value; the expression reads the stored `state`, never the rules composed before it.
       def compile_derive(expression, derive)
-        value = ExpressionSql.compile(derive.tree, "state")
-        "(SELECT CASE WHEN __d IS NULL THEN __s " \
-          "ELSE hecks_tr_insert(__s, #{path_literal(derive.to)}, to_jsonb(__d), " \
-          "#{text_literal("derive #{derive.to}")}) END " \
-          "FROM (SELECT (#{expression}) AS __s) __outer, LATERAL (SELECT #{value} AS __d) __derived)"
+        form("derive", expression: expression, to: path_literal(derive.to),
+                       value: ExpressionSql.compile(derive.tree, "state"), rule: text_literal("derive #{derive.to}"))
       end
 
       # Folds each rule of one kind into `expression`, innermost-first.
@@ -53,26 +69,26 @@ module Hecks
 
       # Wraps `expression` in the rename of one top-level key.
       def compile_rename(expression, old_name, new_name)
-        "hecks_tr_rename(#{expression}, #{text_literal(old_name)}, #{text_literal(new_name)})"
+        form("rename", expression: expression, from: text_literal(old_name), to: text_literal(new_name))
       end
 
       # Wraps `expression` in the move of one path to another.
       def compile_move(expression, move)
-        "hecks_tr_move(#{expression}, #{path_literal(move.from)}, #{path_literal(move.to)}, " \
-          "#{text_literal("move #{move.from} to: #{move.to}")})"
+        form("move", expression: expression, from: path_literal(move.from), to: path_literal(move.to),
+                     rule: text_literal("move #{move.from} to: #{move.to}"))
       end
 
       # Wraps `expression` in the conversion of one path's value through a lookup table.
       def compile_convert(expression, convert)
         pairs = JSON.generate(convert.values.map { |key, value| [key, value] })
-        "hecks_tr_convert(#{expression}, #{path_literal(convert.from)}, #{path_literal(convert.to)}, " \
-          "#{text_literal(pairs)}::jsonb, #{text_literal(convert.from)}, " \
-          "#{text_literal("convert #{convert.from} to: #{convert.to}")})"
+        form("convert", expression: expression, from: path_literal(convert.from), to: path_literal(convert.to),
+                        values: text_literal(pairs), source: text_literal(convert.from),
+                        rule: text_literal("convert #{convert.from} to: #{convert.to}"))
       end
 
       # Wraps `expression` in the removal of one path.
       def compile_drop(expression, name)
-        "hecks_tr_drop(#{expression}, #{path_literal(name)})"
+        form("drop", expression: expression, path: path_literal(name))
       end
 
       # Reports whether an edge's declared rules for an aggregate include a rekey, read
@@ -90,18 +106,15 @@ module Hecks
       def compile_id_expression(declared)
         rekey = declared.rekeys.first
         derive = declared.derives.find { |candidate| candidate.to == rekey.to }
-        "COALESCE(#{ExpressionSql.compile(derive.tree, "state")}, aggregate_id)"
+        form("rekey_to", value: ExpressionSql.compile(derive.tree, "state"))
       end
 
       # Wraps `expression` so a backfill's default lands at its declared path only when
       # nothing is already there, the same rule `Lineage#translate`'s own pass holds to.
       def compile_backfill(expression, backfill)
         name = backfill.name.to_s
-        default_json = JSON.generate(backfill.default)
-        "(SELECT CASE WHEN (hecks_tr_extract(__s, #{path_literal(name)})).present THEN __s " \
-          "ELSE hecks_tr_insert(__s, #{path_literal(name)}, #{text_literal(default_json)}::jsonb, " \
-          "#{text_literal("backfill #{name}")}) END " \
-          "FROM (SELECT (#{expression}) AS __s) __outer)"
+        form("backfill", expression: expression, path: path_literal(name),
+                         default: text_literal(JSON.generate(backfill.default)), rule: text_literal("backfill #{name}"))
       end
 
       # Renders a Ruby value as a single-quoted SQL text literal, escaping embedded quotes.

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/differ.rb

@@ -11,8 +11,8 @@ module Hecks
 
         # Diffs two bluebook IRs into the edge's declarations.
         #
-        # @param held_bluebook [Bluebook::Chapter] the era being translated from
-        # @param current_bluebook [Bluebook::Chapter] the era being translated to
+        # @param held_bluebook [Bluebook::Declaration] the era being translated from
+        # @param current_bluebook [Bluebook::Declaration] the era being translated to
         # @return [Hash{Symbol => Object}] `:aggregates` (Array<Scaffold::ScaffoldedAggregate>),
         #   `:retired` (Array<String>, vanished names with no successor), `:unclaimed`
         #   (Array<String>, vanished names left ambiguous)

data/lib/hecks/ports/persistence/plugins/era.rb

@@ -4,7 +4,6 @@ require_relative "era/era_guard"
 require_relative "era/era_tamper"
 require_relative "era/storage_shape"
 require_relative "era/lineage"
-require_relative "era/postgres_era"
 require_relative "era/translation"
 
 module Hecks

data/lib/hecks/ports/persistence/remote_runtime.rb

@@ -9,11 +9,12 @@ module Hecks
         # Refuses every local write; `project` is an alias and refuses the same way.
         #
         # @return [void] never returns
-        # @raise [Runtime::WiringError] always, pointing the caller at `Runtime::RemoteDispatcher`
+        # @raise [Runtime::WiringError] always, pointing the caller at
+        #   `Adapters::Lambda::RemoteDispatcher`
         def append(*)
           raise Runtime::WiringError,
                 "#{self.class.name} is a remote-runtime delegate — dispatch through " \
-                "Runtime::RemoteDispatcher instead of writing through the repository directly"
+                "Adapters::Lambda::RemoteDispatcher instead of writing through the repository directly"
         end
         alias project append
 

data/lib/hecks/ports/persistence/set_statement.rb

@@ -0,0 +1,29 @@
+module Hecks
+  module Ports
+    module Persistence
+      # One command applied to every row of a query, said without SQL (ADR 0129): the runtime
+      # builds it from the bluebook, and a store that provides `set_transform` compiles it to one
+      # statement in its own dialect. It names fields and parsed expressions, never columns.
+      #
+      # - `query`, `query_args`: the query's specification and arguments, as the store answers it
+      # - `givens`: each given's parsed predicate, every one of which a row must meet
+      # - `assignments`: each {SetStatement::Assignment} the command makes
+      # - `transition`: the lifecycle cases in order, each `[from_states or nil, target]`; nil when
+      #   the command moves no lifecycle
+      # - `from_guard`: the lifecycle states the command is admissible from, or nil
+      # - `arguments`: the command's arguments by name, each a plain scalar an expression reads
+      SetStatement = Struct.new(:query, :query_args, :givens, :assignments, :transition, :from_guard, :arguments,
+                                keyword_init: true)
+
+      class SetStatement
+        # One field a statement writes. `kind` says what `value` is:
+        #
+        # - `:constant`: the value every row takes, already shaped as the record holds it
+        # - `:copy`: the name of the field whose value each row copies
+        # - `:expression`: a parsed expression over the row and the arguments
+        # - `:step`: the Integer added to the field (negative to take away)
+        Assignment = Struct.new(:target, :kind, :value, keyword_init: true)
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/set_transforming.rb

@@ -0,0 +1,30 @@
+require_relative "set_statement"
+
+module Hecks
+  module Ports
+    module Persistence
+      # The repository's door to its adapter's one-statement rewrite (ADR 0129). Mixed into
+      # `AppendOnly`, which supplies `@adapter`.
+      module SetTransforming
+        # Whether the adapter answers a {SetStatement} with one statement. The declared
+        # `provides "set_transform"` says a store should; this says this adapter does.
+        #
+        # @return [Boolean]
+        def set_transform? = @adapter.respond_to?(:apply_set_transform) && @adapter.respond_to?(:set_transform_dialect)
+
+        # @return [String, nil] the dialect the adapter's statement is written in, such as
+        #   `"sqlite"`; nil when it answers no statement
+        def set_transform_dialect = (@adapter.set_transform_dialect if set_transform?)
+
+        # Rewrites every row a statement selects, in one statement, and journals each.
+        #
+        # @param statement [SetStatement] the command over the query
+        # @return [Array<Runtime::Instance>] the rows it updated, as they now stand
+        # @raise [Adapters::SetTransform::Uncompilable] before anything is written, when part of
+        #   the statement has no form in the adapter's dialect
+        # @raise [Adapters::SetTransform::Declined] if the store refused the statement
+        def apply_set_transform(statement) = @adapter.apply_set_transform(statement)
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/state_codec.rb

@@ -159,7 +159,7 @@ module Hecks
         # Decodes one stored value object or entity, looked up by type name.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct that
-        #   declares, or whose chapter declares, the type
+        #   declares, or whose bluebook declares, the type
         # @param type [String] the declared type name, such as `"Address"`
         # @param value [Object] the stored value
         # @return [Hash, Object] a new decoded Hash; `value` unchanged when it is not a Hash or
@@ -249,7 +249,7 @@ module Hecks
         # Checks one stored value object or entity, the mirror of `decode_composite`.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct that
-        #   declares, or whose chapter declares, the type
+        #   declares, or whose bluebook declares, the type
         # @param type [String] the declared type name
         # @param value [Object] the value to inspect
         # @return [Boolean] true when `value` is not a Hash, `type` names neither an entity nor
@@ -264,7 +264,7 @@ module Hecks
         # Maps the declared keys of a stored value object or entity, looked up by type name.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct that
-        #   declares, or whose chapter declares, the type
+        #   declares, or whose bluebook declares, the type
         # @param type [String] the declared type name
         # @return [Hash{Symbol => Bluebook::Attribute, nil}, nil] the entity's fields, else the
         #   unambiguous value object's; nil when `type` names neither

data/lib/hecks/ports/persistence.rb

@@ -8,10 +8,6 @@ require_relative "persistence/remote_runtime"
 require_relative "persistence/null_saga_store"
 require_relative "persistence/state_codec"
 
-# Loaded on first mention: nothing about a domain's own boot needs the dump
-# tooling, and it wants the optional `pg` gem.
-Hecks::Ports::Persistence.autoload(:PostgresDump, File.join(__dir__, "persistence/postgres_dump"))
-
 module Hecks
   module Ports
     # Reopened once BindingPolicy/RepositoryFactory are loaded, adding the port's

data/lib/hecks/ports/projection.rb

@@ -16,11 +16,14 @@ module Hecks
       end
 
       # Builds a worker for the aggregate's first `projected_by` bind; nil when it has none.
+      #
+      # It reads the registry's own authoritative repository, so a projection of an in-process
+      # store (Memory) sees the records the registry holds, not a fresh empty store.
       def worker(registry, domain, aggregate, policy: :refresh)
         bind = binds_for(registry, domain, aggregate).first
         return unless bind
 
-        authoritative = Persistence.repository(registry, domain, aggregate)
+        authoritative = registry.repository(domain, aggregate)
         target = Persistence::RepositoryFactory.build(registry, domain, aggregate, bind,
                                                       recover: true, settings_verb: VERB)
         Worker.new(authoritative, target, policy: policy)

data/lib/hecks/ports/query/cursor.rb

@@ -0,0 +1,131 @@
+require "base64"
+require "delegate"
+require "json"
+require_relative "../../query_specification/field_path"
+require_relative "../../query_specification/common/comparison"
+require_relative "../../query_specification/common/limit_spec"
+
+module Hecks
+  module Ports
+    module Query
+      # The position a cursor query pages by: the row's order value and its identity, as one opaque
+      # token, and the rule for which rows follow it.
+      #
+      # The sequence is the one `Ordering` and `NullPolicy.sql_order` give: the order field in the
+      # declared direction, nulls where `nulls` puts them, identity breaking ties in the same
+      # direction. `SqlKeyset` compiles the same rule into SQL.
+      module Cursor
+        # A token the query did not hand out.
+        class Invalid < ArgumentError; end
+
+        # The decoded position: the order field's comparable value (nil when null) and the row id.
+        Position = Struct.new(:value, :id)
+
+        # A declared query asking for one row more than its page, to learn whether another follows.
+        class Widened < SimpleDelegator
+          # @param declared [QuerySpecification::Common::Options] the cursor query
+          # @param size [Integer] the page size the query's `limit` resolves to
+          def initialize(declared, size)
+            super(declared)
+            @limit = QuerySpecification::Common::LimitSpec.new(value: size + 1)
+          end
+
+          # @return [QuerySpecification::Common::LimitSpec] the page size plus one
+          attr_reader :limit
+        end
+
+        module_function
+
+        # @param value [Object, nil] the row's comparable order value
+        # @param id [String] the row's identity
+        # @return [String] the URL-safe token naming that position
+        def encode(value, id) = Base64.urlsafe_encode64(JSON.generate([json_safe(value), id.to_s]), padding: false)
+
+        # @param token [String, nil] an `after` argument
+        # @return [Position, nil] the position, or nil when there is no token
+        # @raise [Invalid] if the token is not one `encode` made
+        def decode(token)
+          return nil if token.nil? || token.to_s.empty?
+
+          value, id = JSON.parse(Base64.urlsafe_decode64(token.to_s))
+          raise Invalid, "after #{token.inspect} is not a cursor" unless id.is_a?(String)
+
+          Position.new(value, id)
+        rescue JSON::ParserError, ArgumentError, TypeError
+          raise Invalid, "after #{token.inspect} is not a cursor this query handed out"
+        end
+
+        # Whether a null sorts before the valued rows in this query's order.
+        def nulls_first?(direction, policy)
+          case policy&.mode.to_s
+          when "first" then true
+          when "last" then false
+          else direction.to_s.downcase != "desc"
+          end
+        end
+
+        # @param rows [Array<Runtime::Instance, Hash>] rows already in query order
+        # @param declared [QuerySpecification::Common::Options] a cursor query
+        # @param args [Hash] the ask's arguments; `:after` carries the token
+        # @return [Array] the rows following the token's position, all of them with no token
+        def after(rows, declared, args)
+          position = decode(args[:after])
+          return rows unless position
+
+          rows.select { |row| follows?(row, declared, position) }
+        end
+
+        # @return [Boolean] whether `row` comes after `position` in the query's order
+        def follows?(row, declared, position)
+          order_by = declared.order_by
+          value = order_by && comparable_value(row, order_by.field)
+          return (id_of(row) <=> position.id) == 1 unless order_by
+
+          sequence(value, id_of(row), position, order_by, declared.null_semantics).positive?
+        end
+
+        # @return [Integer] -1, 0 or 1: where the row sits against the position in query order
+        def sequence(value, id, position, order_by, policy)
+          first = nulls_first?(order_by.direction, policy)
+          return (value.nil? == first ? -1 : 1) if value.nil? != position.value.nil?
+
+          result = ties_by_id(value.nil? ? 0 : value <=> position.value, id, position.id)
+          order_by.direction.to_s.downcase == "desc" ? -result : result
+        end
+
+        # A tie in the order value (or two values that do not compare) falls to identity.
+        def ties_by_id(compared, id, held_id) = compared.nil? || compared.zero? ? id <=> held_id : compared
+
+        # The token naming the last of `rows`, with the page's ordering read off `declared`.
+        def token_for(row, declared)
+          order_by = declared.order_by
+          encode(order_by && comparable_value(row, order_by.field), id_of(row))
+        end
+
+        # Splits rows fetched one past the page into the page and the token of the next one.
+        #
+        # @param rows [Array] up to `size + 1` rows in query order
+        # @param declared [QuerySpecification::Common::Options] the cursor query, unwidened
+        # @param size [Integer] the page size
+        # @return [Array(Array, String, nil)] the page rows and `after`, nil on the last page
+        def split(rows, declared, size)
+          page = rows.first(size)
+          [page, rows.size > size && !page.empty? ? token_for(page.last, declared) : nil]
+        end
+
+        def comparable_value(row, field)
+          json_safe(QuerySpecification::Common::Comparison.comparable(QuerySpecification::FieldPath.dig(row, field)))
+        end
+
+        def id_of(row) = (row.is_a?(Hash) ? row[:id] : row.id).to_s
+
+        def json_safe(value)
+          case value
+          when nil, String, Numeric, true, false then value
+          else value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/query/in_memory.rb

@@ -1,4 +1,5 @@
 require_relative "ordering"
+require_relative "cursor"
 require_relative "../../runtime/value"
 require_relative "../../query_specification/field_path"
 require_relative "../../query_specification/common/comparison"
@@ -6,8 +7,8 @@ require_relative "../../query_specification/common/comparison"
 module Hecks
   module Ports
     module Query
-      # Applies wheres, order_by, offset and limit to an Array of records, in the same order
-      # as `SqlQueryBuilder` so every adapter answers the same page.
+      # Applies wheres, order_by, a cursor's position, offset and limit to an Array of records, in
+      # the same order as `SqlQueryBuilder` so every adapter answers the same page.
       module InMemory
         FieldPath = QuerySpecification::FieldPath
         Comparison = QuerySpecification::Common::Comparison
@@ -24,12 +25,17 @@ module Hecks
         # @return [Array<Runtime::Instance, Hash>] the matching records, ordered and paged
         def execute(records, declared, args = {}, registry: nil)
           matched = filter(records, declared, args, registry)
-          matched = order(matched, declared)
-          # Offset before limit, as SQL means `LIMIT n OFFSET m`; the reverse order returns a short
-          # or empty page (`limit 10, offset 10` would drop everything).
-          matched = matched.drop(resolve(declared.offset.value, args).to_i) if declared.offset
-          matched = matched.first(resolve(declared.limit.value, args).to_i) if declared.limit
-          matched
+          page(order(matched, declared), declared, args)
+        end
+
+        # The cursor's position, then the offset, then the limit.
+        #
+        # Offset before limit, as SQL means `LIMIT n OFFSET m`; the reverse order returns a short
+        # or empty page (`limit 10, offset 10` would drop everything).
+        def page(ordered, declared, args)
+          ordered = Cursor.after(ordered, declared, args) if declared.cursor
+          ordered = ordered.drop(resolve(declared.offset.value, args).to_i) if declared.offset
+          declared.limit ? ordered.first(resolve(declared.limit.value, args).to_i) : ordered
         end
 
         def filter(records, declared, args, registry)
@@ -41,8 +47,9 @@ module Hecks
         end
 
         def order(matched, declared)
-          field = declared.order_by&.field
-          Ordering.apply(matched, declared.order_by, declared.null_semantics,
+          order_by = declared.order_by
+          field = order_by&.field
+          Ordering.apply(matched, order_by, declared.null_semantics,
                          identity: ->(record) { record.id.to_s }) { |record| comparable(FieldPath.dig(record, field)) }
         end
 

data/lib/hecks/ports/query.rb

@@ -33,8 +33,9 @@ module Hecks
       def validate!(specification, adapter)
         raise Unsupported, "a query cannot combine cursor and offset pagination" if specification.cursor && specification.offset
 
-        return if specification.inspection.nil? || adapter.respond_to?(:inspect_query)
-        return if specification.inspection.mode.to_s == "sql" && adapter.respond_to?(:query)
+        inspection = specification.inspection
+        return if inspection.nil? || adapter.respond_to?(:inspect_query)
+        return if inspection.mode.to_s == "sql" && adapter.respond_to?(:query)
 
         raise Unsupported, "#{adapter.class} cannot inspect generated queries"
       end
@@ -43,4 +44,5 @@ module Hecks
 end
 
 require_relative "query/ordering"
+require_relative "query/cursor"
 require_relative "query/in_memory"

data/lib/hecks/ports.rb

@@ -17,6 +17,7 @@ require_relative "ports/identity_generation"
 require_relative "ports/key_vault"
 require_relative "ports/authorization"
 require_relative "ports/identity_resolution"
+require_relative "ports/authentication"
 require_relative "ports/access_control"
 require_relative "ports/identity_assignment"
 require_relative "ports/agent"

data/lib/hecks/projection_files/expression_tables.rb

@@ -31,9 +31,9 @@ module Hecks
 
       # @return [Hash{String => Hash}] each comparison's declared algebra, by operator symbol
       def comparison_algebra
-        vocabulary = chapter.aggregates.find { |aggregate| aggregate.name == "Vocabulary" }
-        vocabulary.value_objects.find { |value_object| value_object.hecks_name == "Comparison" }
-                  .members.to_h { |row| [row.to_h.values.first, row.to_h] }
+        vocabulary = declaration.aggregates.find { |aggregate| aggregate.name == "Vocabulary" }
+        comparison = vocabulary.value_objects.find { |value_object| value_object.hecks_name == "Comparison" }
+        comparison.members.to_h { |row| [row.to_h.values.first, row.to_h] }
       end
 
       # @param operator [Hash] one admitted operator

data/lib/hecks/projection_files/sentence_table.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Hecks
+  module ProjectionFiles
+    # The sentence-table projection: the phrases an author may write, as the Rust parser's table.
+    # Extended onto `ProjectionFiles`.
+    module SentenceTable
+      # @param root [String] the checkout
+      # @return [Result] `rust/parser/src/phrases.rs`, from the Sentence bluebook
+      def phrase_table(root)
+        require "hecks"
+        text = Projector.call(:phrase_table, bluebook: Projections::PhraseTable.declaration)
+        Result.new({ File.join(root, "rust/parser/src/phrases.rs") => text }, [])
+      end
+    end
+  end
+end

data/lib/hecks/projection_files.rb

@@ -6,13 +6,14 @@ require "tempfile"
 require_relative "rust_format"
 require_relative "projection_files/texts"
 require_relative "projection_files/expression_tables"
+require_relative "projection_files/sentence_table"
 
 module Hecks
   # What each `project_*` generator of the language writes, held as data: absolute path to text.
   #
   # The tables of the language (the model's holding half, the vocabulary, the parser's keywords, the
   # Rust vocabulary, reserved names, field hints, the expression tables and the DSL reference) are
-  # projected from the Bluebook chapter's own declarations. Building them apart from writing them
+  # projected from the Bluebook bluebook's own declarations. Building them apart from writing them
   # lets a caller compare a projection with the tree before anything is changed: a
   # `hecks project_*` verb writes the answer, and the Hecks domain's Language commands report
   # drift and write only when confirmed.
@@ -38,11 +39,12 @@ module Hecks
     }.freeze
 
     # Names of the projections, in the order a full regeneration runs them.
-    NAMES = %i[model vocabulary rust_vocabulary reserved_names parser_table bootstrap_table
+    NAMES = %i[model vocabulary rust_vocabulary reserved_names parser_table phrase_table bootstrap_table
                field_hints expression_tables reference].freeze
 
     extend Texts
     extend ExpressionTables
+    extend SentenceTable
 
     module_function
 
@@ -100,10 +102,10 @@ module Hecks
     end
 
     # @param root [String] the checkout
-    # @return [Result] the model's holding half, one file for each thing the chapter holds
+    # @return [Result] the model's holding half, one file for each thing the bluebook holds
     def model(root)
       require "hecks"
-      files = Projector.call(:model, bluebook: chapter)
+      files = Projector.call(:model, bluebook: declaration)
       out = File.join(root, "lib/hecks/bluebook")
       Result.new(files.to_h { |relative, text| [File.join(out, relative), text] }, [])
     end
@@ -121,7 +123,7 @@ module Hecks
     def rust_vocabulary(root)
       require "hecks"
       kernel = File.join(root, "rust/src/kernel")
-      files = Projector.call(:rust_vocabulary, bluebook: chapter)
+      files = Projector.call(:rust_vocabulary, bluebook: declaration)
       content = files.to_h { |relative, text| [File.join(kernel, relative), text] }
       Result.new(content, Dir.glob(File.join(kernel, "vocab", "*.rs")) - content.keys)
     end
@@ -165,13 +167,14 @@ module Hecks
     end
 
     # @param root [String] the checkout
-    # @return [Result] `rust/host/src/field_hints.rs`, the hints the host's form fields guess from
+    # @return [Result] `rust/host/core/src/field_hints.rs`, the hints the host's form fields guess
+    #   from
     def field_hints(root)
       require "hecks"
-      vocabulary = chapter.aggregates.find { |aggregate| aggregate.hecks_name == "Vocabulary" }
+      vocabulary = declaration.aggregates.find { |aggregate| aggregate.hecks_name == "Vocabulary" }
       field_hint = vocabulary.value_objects.find { |value_object| value_object.hecks_name == "FieldHint" }
       hints = field_hint.members.map(&:to_h)
-      Result.new({ File.join(root, "rust/host/src/field_hints.rs") => field_hints_text(hints) }, [])
+      Result.new({ File.join(root, "rust/host/core/src/field_hints.rs") => field_hints_text(hints) }, [])
     end
 
     # The DSL reference pages and the README regions generated from the same declarations.
@@ -181,7 +184,7 @@ module Hecks
     def reference(root)
       require "hecks"
       directory = File.join(root, "docs/implemented/reference")
-      pages = Projector.call(:reference, bluebook: chapter, options: { from: directory })
+      pages = Projector.call(:reference, bluebook: declaration, options: { from: directory })
       content = pages.to_h { |relative, text| [File.join(directory, relative), text] }
       readme = File.join(root, "README.md")
       content[readme] = Doc::Reference.render_readme(root, File.read(readme))
@@ -189,14 +192,14 @@ module Hecks
     end
 
     # @param projection [Symbol] a projection registered with the projector
-    # @return [String] what it projects from the Bluebook chapter, as the text a file holds
+    # @return [String] what it projects from the Bluebook bluebook, as the text a file holds
     def artifact_text(projection)
-      artifact = Projector.call(projection, bluebook: chapter)
+      artifact = Projector.call(projection, bluebook: declaration)
       artifact.is_a?(String) ? artifact : "#{JSON.pretty_generate(artifact)}\n"
     end
 
-    # @return [Bluebook::Aggregate] the Bluebook chapter, which every projection reads
-    def chapter
+    # @return [Bluebook::Aggregate] the Bluebook bluebook, which every projection reads
+    def declaration
       Bluebook::MetaValidator.grammar_registry.bluebook("Bluebook")
     end
   end

data/lib/hecks/projections/bootstrap_table.rb

@@ -2,12 +2,12 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # Projects lib/hecks/bluebook/dsl/bootstrap_table.rb from the chapter's Keyword rows.
+    # Projects lib/hecks/bluebook/dsl/bootstrap_table.rb from the bluebook's Keyword rows.
     # Committed, not built at boot: it is read before the grammar table exists.
     #
-    #   Projector.call(:bootstrap_table, bluebook: <the Bluebook chapter>)
+    #   Projector.call(:bootstrap_table, bluebook: <the Bluebook bluebook>)
     #
-    # Every live row is included, not only those a bootstrap chapter calls.
+    # Every live row is included, not only those a bootstrap bluebook calls.
     module BootstrapTable
       extend Projector::Target