hecks 5.0.0 → 6.0.0

data/lib/hecks/bluebook/expression/evaluator.rb

@@ -1,6 +1,7 @@
 require "json"
 require_relative "../../vocabulary"
 require_relative "evaluator/parser"
+require_relative "../../switches"
 
 module Hecks
   module Bluebook
@@ -11,16 +12,18 @@ module Hecks
         Operator = Struct.new(:symbol, :compares_less_than, :compares_equal, :negated, keyword_init: true)
 
         # Six comparison operators reduced to two primitives (less_than, equal).
-        # Read from the checked-in projection because the evaluator runs while the chapter boots.
+        # Read from the checked-in projection because the evaluator runs while the bluebook boots.
         # Freshness: spec/operators_export_spec.rb; conformance: spec/operator_conformance_spec.rb.
         PROJECTION = JSON.parse(
           File.read(File.join(__dir__, "projection.json")), symbolize_names: true
         ).freeze
 
-        OPERATORS = PROJECTION.fetch(:operators)
-                              .select { |row| row[:category] == "comparison" }
-                              .map { |row| Operator.new(**row.slice(:symbol, :compares_less_than, :compares_equal, :negated)) }
-                              .freeze
+        # The projection's comparison-operator rows, as plain Hashes.
+        COMPARISON_ROWS = PROJECTION.fetch(:operators).select { |row| row[:category] == "comparison" }
+
+        OPERATORS = COMPARISON_ROWS
+                    .map { |row| Operator.new(**row.slice(:symbol, :compares_less_than, :compares_equal, :negated)) }
+                    .freeze
 
         COMPARISONS = OPERATORS.map(&:symbol).freeze
 
@@ -29,7 +32,10 @@ module Hecks
         Or      = Struct.new(:left, :right, keyword_init: true)
         And     = Struct.new(:left, :right, keyword_init: true)
         Not     = Struct.new(:node, keyword_init: true)
-        Compare = Struct.new(:operator, :left, :right, keyword_init: true)
+        Compare = Struct.new(:operator, :left, :right, keyword_init: true) do
+          # @return [String] the comparison's operator as written, such as `">="`
+          def operator_symbol = operator.symbol
+        end
         Include = Struct.new(:haystack, :needle, keyword_init: true)
         Resolve = Struct.new(:expr, keyword_init: true)
 
@@ -58,7 +64,7 @@ module Hecks
         end
 
         # Evaluates a Given/Invariant by walking its structured `ast`, falling back to
-        # parsing `canonical` when the rule has none. HECKS_EVAL=string forces the text path.
+        # parsing `canonical` when the rule has none.
         #
         # @param rule [Bluebook::Given, Bluebook::Invariant] the rule to evaluate
         # @param state [Hash{Symbol => Object}] stored attribute values a `Resolve`/`Compare` leaf
@@ -69,8 +75,6 @@ module Hecks
         # @raise [EvaluationError] if `rule` resolves an unknown attribute/argument, or
         #   misapplies an operation
         def call_rule(rule, state, attrs = {})
-          return call(rule.canonical, state, attrs) if ENV["HECKS_EVAL"] == "string"
-
           interpret(ast_cache[rule.canonical] ||= nodes_for(rule), state, attrs)
         end
 

data/lib/hecks/bluebook/expression/projection.json

@@ -245,6 +245,12 @@
       "category": "arithmetic",
       "precedence": 7,
       "arity": 2
+    },
+    {
+      "symbol": ".sum",
+      "category": "enumeration",
+      "precedence": 10,
+      "arity": 2
     }
   ],
   "normalisations": [

data/lib/hecks/bluebook/expression/resolver/block_predicates.rb

@@ -22,10 +22,16 @@ module Hecks
         # Shares `param`/`predicate` with `BlockPredicate` so `interpret_with_element` serves both.
         Find = Struct.new(:receiver, :param, :predicate, :path, keyword_init: true)
 
+        # `receiver.sum { |x| EXPRESSION }`: the total of a number worked out for each element,
+        # as `items.sum { |i| i.quantity * i.price }`. Shares `param`/`predicate` with `Find`,
+        # though the block holds a number, not a test; an empty list totals 0.
+        Sum = Struct.new(:receiver, :param, :predicate, keyword_init: true)
+
         module_function
 
-        # Every suffix that opens a `{ |x| ... }` block; `.find` builds a `Find`, not a mode.
-        BLOCK_OPENER_SUFFIXES = (BLOCK_PREDICATE_MODES.keys + ["find"]).freeze
+        # Every suffix that opens a `{ |x| ... }` block; `.find` builds a `Find` and `.sum` a `Sum`,
+        # not a mode.
+        BLOCK_OPENER_SUFFIXES = (BLOCK_PREDICATE_MODES.keys + %w[find sum]).freeze
 
         # Receiver text, suffix and block parameter of an opener, up to the first body character.
         BLOCK_OPENER_PATTERN =
@@ -52,10 +58,21 @@ module Hecks
           predicate = Evaluator.parse(expr[header.end(0)...body_end].strip)
           rest = expr[(body_end + 1)..].strip
           return find_node(header, predicate, rest) if header[2] == "find"
+          return sum_node(header, predicate, rest) if header[2] == "sum"
 
           block_predicate_node(header, predicate, rest)
         end
 
+        # @param header [MatchData] the opener match: receiver text, suffix, block parameter
+        # @param predicate [Object] the parsed block body, a number rather than a test
+        # @param rest [String] the text after the closing brace
+        # @return [Sum, nil] the node, or nil unless the block ends `expr`
+        def sum_node(header, predicate, rest)
+          return nil unless rest.empty?
+
+          Sum.new(receiver: parse(header[1]), param: header[3], predicate: predicate)
+        end
+
         # @param header [MatchData] the opener match: receiver text, suffix, block parameter
         # @param predicate [Object] the parsed block body
         # @param rest [String] the text after the closing brace
@@ -112,6 +129,37 @@ module Hecks
           Evaluator.interpret(node.predicate, state, attrs.merge(node.param.to_sym => element))
         end
 
+        # `.sum { |x| EXPRESSION }` — the block's number for every element, added up with the same
+        # 64-bit overflow check an addition has. An empty list is 0.
+        #
+        # @param node [Sum] the parsed `.sum` node
+        # @param collection [Object] the interpreted receiver, expected to be an Array
+        # @param state [Hash{Symbol => Object}] the record's own current state
+        # @param attrs [Hash{Symbol => Object}] the command's own bound arguments
+        # @return [Integer, Float] the total
+        # @raise [EvaluationError] if `collection` is not an Array, or a term is not a number
+        def summed_of(node, collection, state, attrs)
+          raise EvaluationError, "sum expects a list, got #{describe(collection)}" unless collection.is_a?(Array)
+
+          collection.reduce(0) { |total, element| add(total, term_of(node, element, state, attrs)) }
+        end
+
+        # What `node`'s block works out for `element`: the value of a plain expression, or, for a
+        # block that is a test, its true or false, which the addition then refuses.
+        #
+        # @param node [Sum] the parsed `.sum` node
+        # @param element [Object] the collection element to bind
+        # @param state [Hash{Symbol => Object}] the record's current state
+        # @param attrs [Hash{Symbol => Object}] the command's bound arguments
+        # @return [Object] the block's value for `element`
+        def term_of(node, element, state, attrs)
+          bound = attrs.merge(node.param.to_sym => element)
+          body = node.predicate
+          return unwrap_scalar(interpret(body.expr, state, bound)) if body.is_a?(Evaluator::Resolve)
+
+          Evaluator.interpret(body, state, bound)
+        end
+
         # `.find { |x| PREDICATE }` — the first element the predicate accepts, then `node.path`
         # walked through it. A miss yields nil rather than raising: no match is a normal outcome.
         #

data/lib/hecks/bluebook/expression/resolver/lookups.rb

@@ -54,7 +54,8 @@ module Hecks
         end
 
         def sole_field_of(value)
-          sole = value.value_object.sole_attribute
+          definition = value.value_object
+          sole = definition.sole_attribute
           sole ? value[sole.name] : value
         end
 

data/lib/hecks/bluebook/expression/resolver/operations.rb

@@ -28,6 +28,7 @@ module Hecks
           Last           => ->(_node, value, _state, _attrs) { Resolver.last_of(value) },
           First          => ->(_node, value, _state, _attrs) { Resolver.first_of(value) },
           Find           => ->(node, value, state, attrs) { Resolver.found_of(node, value, state, attrs) },
+          Sum            => ->(node, value, state, attrs) { Resolver.summed_of(node, value, state, attrs) },
           StartsWith     => ->(node, value, _state, _attrs) { Resolver.starts_with?(value, node.substring) },
           EndsWith       => ->(node, value, _state, _attrs) { Resolver.ends_with?(value, node.substring) },
           BlockPredicate => ->(node, value, state, attrs) { Resolver.evaluate_block_predicate(node, value, state, attrs) }

data/lib/hecks/bluebook/expression/resolver/parsing.rb

@@ -16,6 +16,18 @@ module Hecks
           [/\A(.+)\.set\?\z/, Assignment, { negated: false }], [/\A(.+)\.unset\?\z/, Assignment, { negated: true }]
         ].freeze
 
+        # A receiver followed by `.length`, capturing the receiver.
+        LENGTH_CALL = /\A(.+)\.length\z/
+
+        # An optionally negative whole-number literal.
+        INTEGER_LITERAL = /\A-?\d+\z/
+
+        # An optionally negative decimal literal; the digits before the point may be left out.
+        FLOAT_LITERAL = /\A-?\d*\.\d+\z/
+
+        # A `receiver.match?(/pattern/flags)` call, capturing the receiver, pattern and flags.
+        MATCHES_REGEX_CALL = %r{\A(.+)\.match\?\(/(.*)/([a-z]*)\)\z}m
+
         # The strip family, each matched as `<receiver>.<call>`, naming which ends it trims.
         STRIP_SUFFIXES = [
           [/\A(.+)\.strip\z/, :both], [/\A(.+)\.lstrip\z/, :left], [/\A(.+)\.rstrip\z/, :right]
@@ -52,7 +64,7 @@ module Hecks
         end
 
         def parse_length(expr)
-          length = expr.match(/\A(.+)\.length\z/)
+          length = expr.match(LENGTH_CALL)
           Size.new(receiver: parse(length[1])) if length
         end
 
@@ -60,10 +72,10 @@ module Hecks
           return StringLiteral.new(value: expr[1..-2]) if quoted?(expr)
 
           case expr
-          when /\A-?\d+\z/       then IntegerLiteral.new(value: Integer(expr, 10))
-          when /\A-?\d*\.\d+\z/  then FloatLiteral.new(value: Float(expr))
-          when "true", "false"   then BoolLiteral.new(value: expr == "true")
-          when "nil"             then NilLiteral.new
+          when INTEGER_LITERAL then IntegerLiteral.new(value: Integer(expr, 10))
+          when FLOAT_LITERAL   then FloatLiteral.new(value: Float(expr))
+          when "true", "false" then BoolLiteral.new(value: expr == "true")
+          when "nil"           then NilLiteral.new
           end
         end
 
@@ -73,19 +85,13 @@ module Hecks
         end
 
         # The additive level: the last top-level `+` or binary `-`, so `a - b + c` is `(a - b) + c`.
-        def parse_additive(expr)
-          parse_binary(expr, ADDITIVE)
-        end
+        def parse_additive(expr) = parse_binary(expr, ADDITIVE)
 
         # The multiplicative level, binding tighter than the additive one.
-        def parse_multiplicative(expr)
-          parse_binary(expr, MULTIPLICATIVE)
-        end
+        def parse_multiplicative(expr) = parse_binary(expr, MULTIPLICATIVE)
 
         # A parenthesised group reads as what it wraps.
-        def parse_group(expr)
-          parse(expr[1..-2]) if grouped?(expr)
-        end
+        def parse_group(expr) = (parse(expr[1..-2]) if grouped?(expr))
 
         def parse_binary(expr, table)
           operator, left, right = split_last_binary(expr, table.keys)
@@ -119,7 +125,7 @@ module Hecks
         end
 
         def parse_matches_regex(expr)
-          match = expr.match(%r{\A(.+)\.match\?\(/(.*)/([a-z]*)\)\z}m)
+          match = expr.match(MATCHES_REGEX_CALL)
           MatchesRegex.new(receiver: parse(match[1]), pattern: match[2], flags: match[3]) if match
         end
 

data/lib/hecks/bluebook/expression/resolver/scanning.rb

@@ -10,6 +10,9 @@ module Hecks
         # Quote characters a leaf expression may open a string literal with.
         QUOTES = ['"', "'"].freeze
 
+        # A final character that ends an operand: a word character, a closing bracket or a quote.
+        OPERAND_END = /[[:alnum:]_)\]"']\z/
+
         # How each bracket moves the nesting depth for a split on `+` or `,`. `{`/`}` and
         # `[`/`]` count like parens, so a `+` inside a block body or an array element is not this
         # expression's own addition.
@@ -88,7 +91,7 @@ module Hecks
         def binary_position?(expr, index, char)
           return true unless char == "-"
 
-          expr[0...index].rstrip.match?(/[[:alnum:]_)\]"']\z/)
+          expr[0...index].rstrip.match?(OPERAND_END)
         end
 
         # Whether `expr` is one parenthesised group: its first `(` closes at its last character.

data/lib/hecks/bluebook/expression.rb

@@ -1,7 +1,7 @@
 module Hecks
   module Bluebook
     # The expression language a bluebook's predicates are written in —
-    # canonicalised (canonical_form), resolved against a chapter's names
+    # canonicalised (canonical_form), resolved against a bluebook's names
     # (resolver), and evaluated (evaluator).
     module Expression
     end

data/lib/hecks/bluebook/hecksagon.rb

@@ -14,13 +14,37 @@ module Hecks
     # `defaults` maps a field's name to the value used when the world gives none; a string may hold
     # a `{name}` or `{storage_name}` placeholder, filled from the aggregate the adapter is built
     # for.
-    Adapter = Struct.new(:name, :port, :fields, :secrets, :defaults, keyword_init: true) do
+    #
+    # A plugin adapter instead `runs` a `.wasm` module beside its `.adapter` file (`source_dir`)
+    # and names the queries it `answers` (`"Bluebook::Aggregate.Query"`); it needs no port, and the
+    # runtime binds each query it answers without a hecksagon line.
+    #
+    # `provides` names what the adapter can do beyond its port's contract, such as
+    # `"set_transform"`; a caller asks before relying on it.
+    Adapter = Struct.new(:name, :port, :fields, :secrets, :defaults, :answers, :runs, :provides, :source_dir,
+                         keyword_init: true) do
       def declares?(field) = all_fields.include?(field.to_sym)
 
       def all_fields = (fields || []) + (secrets || [])
 
       # @return [Hash{Symbol => Object}] the declared defaults, empty when none
       def declared_defaults = defaults || {}
+
+      # @return [Array<String>] the qualified queries this adapter answers, empty when none
+      def answered_queries = answers || []
+
+      # @return [Array<String>] the capabilities this adapter provides, empty when none
+      def capabilities = provides || []
+
+      # @param capability [String, Symbol] a capability's name, such as `"set_transform"`
+      # @return [Boolean] whether this adapter declares `provides` for it
+      def provides?(capability) = capabilities.include?(capability.to_s)
+
+      # @return [Boolean] whether this adapter is a wasm plugin
+      def plugin? = !runs.nil?
+
+      # @return [String, nil] where the plugin's module is, beside its `.adapter` file
+      def plugin_path = runs && File.expand_path(runs, source_dir || Dir.pwd)
     end
 
     Bind = Struct.new(:aggregate, :verb, :adapter, :role, keyword_init: true) do
@@ -28,18 +52,19 @@ module Hecks
       def aggregate_name = Naming.demodulise(aggregate)
     end
 
-    # One chapter a hecksagon attaches, with where it was found.
+    # One bluebook a hecksagon attaches, with where it was found.
     #
-    # `source` is `:gem` for a chapter the gem carries (a framework member such as Governance,
-    # or a language chapter such as Deploy) and `:vendor` for a package vendored into the
-    # consuming project, whose `name` is the package's directory name (`"membership"`).
-    Attachment = Struct.new(:name, :source, keyword_init: true) do
-      # @return [Boolean] whether the chapter is a vendored package
+    # `source` is `:gem` for a bluebook the gem carries (a framework member such as Governance,
+    # or a language bluebook such as Deploy) and `:vendor` for a package vendored into the
+    # consuming project, whose `name` is the package's directory name (`"membership"`) and whose
+    # `bluebook` is the name its bluebook declares, which the directory name need not spell.
+    Attachment = Struct.new(:name, :source, :declaration, keyword_init: true) do
+      # @return [Boolean] whether the bluebook is a vendored package
       def vendor? = source == :vendor
 
-      # @return [String] the chapter's name in the registry: a gem chapter's own name, a
-      #   vendored package's directory name in Pascal case
-      def chapter_name = vendor? ? Naming.pascal(name) : name
+      # @return [String] the bluebook's name in the registry: a gem bluebook's own name, a
+      #   vendored package's declared bluebook, else its directory name in Pascal case
+      def declaration_name = declaration || (vendor? ? Naming.pascal(name) : name)
 
       # @return [Hash{Symbol => String}] the attachment as plain data
       def to_h = { name: name.to_s, source: source.to_s }
@@ -75,10 +100,10 @@ module Hecks
       # @param binds [Array<Bluebook::Bind>] the declared adapter binds
       # @param subscriptions [Array<String, Symbol>] the external events this domain
       #   subscribes to
-      # @param attachments [Array<Bluebook::Attachment>] every chapter this hecksagon attaches,
+      # @param attachments [Array<Bluebook::Attachment>] every bluebook this hecksagon attaches,
       #   each with its source (`:gem` or `:vendor`)
-      # @param bounded [Boolean] whether this chapter is an explicit bounded context
-      #   (consumer-owned; `attaches` marks attached chapters bounded on the registry instead)
+      # @param bounded [Boolean] whether this bluebook is an explicit bounded context
+      #   (consumer-owned; `attaches` marks attached bluebooks bounded on the registry instead)
       # @param translates [Array<String>] names of `translates` ACL blocks declared here
       # @param driving [Array<String>] the driving adapters `driven_by` admits; empty admits all
       def initialize(domain:, **given)
@@ -89,22 +114,22 @@ module Hecks
         @driving            = Array(@driving).map(&:to_s)
       end
 
-      # Says whether this hecksagon marked its own chapter `bounded`.
+      # Says whether this hecksagon marked its own bluebook `bounded`.
       #
       # @return [Boolean] whether `bounded` was declared on this block
       def bounded? = @bounded
 
-      # Every chapter this hecksagon brings into its domain's registry, gem and vendored alike.
+      # Every bluebook this hecksagon brings into its domain's registry, gem and vendored alike.
       #
-      # @return [Array<String>] the chapters' names as the registry holds them, in the order
+      # @return [Array<String>] the bluebooks' names as the registry holds them, in the order
       #   they were attached
-      def member_chapters = attachments.map(&:chapter_name)
+      def member_bluebooks = attachments.map(&:declaration_name)
 
-      # Says whether this hecksagon attaches a chapter, whatever its source.
+      # Says whether this hecksagon attaches a bluebook, whatever its source.
       #
-      # @param chapter [String, Symbol] a chapter's name as the registry holds it
-      # @return [Boolean] whether that chapter is attached here
-      def attaches?(chapter) = member_chapters.include?(chapter.to_s)
+      # @param bluebook [String, Symbol] a bluebook's name as the registry holds it
+      # @return [Boolean] whether that bluebook is attached here
+      def attaches?(declaration) = member_bluebooks.include?(declaration.to_s)
 
       # Says whether a driving adapter may reach this hecksagon's domain: every adapter may when
       # none is declared, and only the declared ones may once any is.
@@ -142,11 +167,11 @@ module Hecks
       #   if none is declared
       # @param settings [Hash] the declared adapter bind settings, keyed by verb and,
       #   for a qualified entry, `"verb:adapter"`
-      # @param default_database [String, nil] the connection every chapter's
+      # @param default_database [String, nil] the connection every bluebook's
       #   database-taking persistence adapter uses unless its own settings name one,
       #   or `nil` if none is declared
       # @param default_adapter [String, nil] the persistence adapter every aggregate
-      #   binds to unless its chapter's hecksagon binds it, or `nil` if none is declared
+      #   binds to unless its bluebook's hecksagon binds it, or `nil` if none is declared
       def initialize(domain:, **given)
         KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
         @domain           = domain.to_s

data/lib/hecks/bluebook/meta_validator/adapter_judge.rb

@@ -36,9 +36,12 @@ module Hecks
         end
 
         def judge!
-          send_to("Adapter::Adapter.Declare", @adapter.name, name: v(@adapter.name), port: v(@adapter.port))
+          send_to("Adapter::Adapter.Declare", @adapter.name, name: v(@adapter.name), port: v(@adapter.port),
+                                                             runs: v(@adapter.runs))
           add_fields
           add_all("AddSecret", @adapter.secrets)
+          add_all("AnswerQuery", @adapter.answered_queries)
+          add_all("Provide", @adapter.capabilities)
         end
 
         # Offers one `AddField` per field, each with its declared default when it has one.

data/lib/hecks/bluebook/meta_validator/judge/cells.rb

@@ -43,7 +43,7 @@ module Hecks
           end
 
           # A value object's type may be declared on a different aggregate
-          # in the same chapter; the local aggregate is tried first, then
+          # in the same bluebook; the local aggregate is tried first, then
           # the first (declaration-order) other aggregate that declares it.
           def owning_aggregate_id(id, value)
             local = @bluebook.aggregates.find { |aggregate| Naming.identity([@bluebook.name, aggregate.name]) == id }

data/lib/hecks/bluebook/meta_validator/judge/identity.rb

@@ -49,7 +49,8 @@ module Hecks
           def v_scalar(held)
             return held.to_s unless held.respond_to?(:to_h) && !held.is_a?(String)
 
-            held.to_h.values.first.to_s
+            values = held.to_h.values
+            values.first.to_s
           end
 
           # Each identity field comes from one of three places: the parent

data/lib/hecks/bluebook/meta_validator/modes.rb

@@ -14,16 +14,16 @@ module Hecks
         # @return [Boolean]
         def bootstrapping? = @bootstrapping
 
-        # Whether `call` is queuing chapters instead of judging them, while a
-        # chapter's own files are still being merged (see `defer`).
+        # Whether `call` is queuing bluebooks instead of judging them, while a
+        # bluebook's own files are still being merged (see `defer`).
         #
         # @return [Boolean]
         def deferring? = @deferring
 
-        # Queues every chapter `call` sees while the block runs, instead of
-        # judging them immediately (see `deferred_chapters`).
+        # Queues every bluebook `call` sees while the block runs, instead of
+        # judging them immediately (see `deferred_bluebooks`).
         #
-        # @yield the caller's own load of every file in one chapter window
+        # @yield the caller's own load of every file in one bluebook window
         # @return [Object] the block's own return value
         def defer
           previous   = @deferring
@@ -33,52 +33,52 @@ module Hecks
           @deferring = previous
         end
 
-        # The chapters queued while `defer`'s block ran, awaiting
+        # The bluebooks queued while `defer`'s block ran, awaiting
         # `judge_deferred!`.
         #
-        # @return [Array<String>] each deferred chapter's own `hecks_name`,
+        # @return [Array<String>] each deferred bluebook's own `hecks_name`,
         #   queued during the current or most recent `defer` window
-        def deferred_chapters = @deferred_chapters ||= []
+        def deferred_bluebooks = @deferred_bluebooks ||= []
 
-        # Judges every chapter queued by `defer`, once each, then clears the
+        # Judges every bluebook queued by `defer`, once each, then clears the
         # queue.
         #
         # @param registry [Runtime::Registry, nil] the registry to judge
         #   against; a no-op if `nil`
         # @return [void]
-        # @raise [DSL::Malformed] if a chapter's own whole-chapter battery
+        # @raise [DSL::Malformed] if a bluebook's own whole-bluebook battery
         #   (`BluebookBuilder.validate_assembled!`) or the meta-domain itself
         #   (`call`) refuses it
         def judge_deferred!(registry)
-          pending = deferred_chapters.uniq
-          @deferred_chapters = []
+          pending = deferred_bluebooks.uniq
+          @deferred_bluebooks = []
           return unless registry
 
-          pending.each { |name| judge_chapter!(registry, name) }
+          pending.each { |name| judge_bluebook!(registry, name) }
         end
 
-        # Judges one deferred chapter once its own files are all merged.
+        # Judges one deferred bluebook once its own files are all merged.
         #
-        # @param registry [Runtime::Registry] the registry holding the chapter
-        # @param name [String] the chapter's `hecks_name`
+        # @param registry [Runtime::Registry] the registry holding the bluebook
+        # @param name [String] the bluebook's `hecks_name`
         # @return [void]
-        def judge_chapter!(registry, name)
-          chapter = registry.bluebook(name)
-          return unless chapter
+        def judge_bluebook!(registry, name)
+          declaration = registry.bluebook(name)
+          return unless declaration
 
-          # Bare chapter-level givens must resolve before anything below
+          # Bare bluebook-level givens must resolve before anything below
           # reads a `Given`'s fields. The `raise` block never runs — this
-          # chapter's builder is always already open by the time `chapter` exists.
+          # bluebook's builder is always already open by the time `bluebook` exists.
           builder = registry.bluebook_builder(name) { raise Error, "internal: no open builder for #{name}" }
-          builder.resolve_pending_chapter_givens!
+          builder.resolve_pending_bluebook_givens!
           # Same, one level down: entity-scoped pending givens.
-          builder.resolve_pending_chapter_entity_givens!
+          builder.resolve_pending_bluebook_entity_givens!
 
-          # Whole-chapter checks (hops, projected fields, event shapes) were
-          # skipped per file while deferring; `chapter` now holds every
+          # Whole-bluebook checks (hops, projected fields, event shapes) were
+          # skipped per file while deferring; `bluebook` now holds every
           # file's declarations, so they run once here instead of per file.
-          DSL::BluebookBuilder.validate_assembled!(chapter)
-          registry.add_bluebook(call(chapter))
+          DSL::BluebookBuilder.validate_assembled!(declaration)
+          registry.add_bluebook(call(declaration))
         end
 
         # Whether meta-domain judging is off (ignored while a fixpoint build

data/lib/hecks/bluebook/meta_validator/plan.rb

@@ -12,16 +12,16 @@ module Hecks
         # Reads the language's own self-description off `registry`.
         #
         # @param registry [Runtime::Registry] a registry with the language's
-        #   own "Bluebook" chapter already judged and assembled
-        # @return [Plan] the plan, built from that chapter's own aggregates
+        #   own "Bluebook" bluebook already judged and assembled
+        # @return [Plan] the plan, built from that bluebook's own aggregates
         def self.for(registry)
           new(registry.bluebook("Bluebook"))
         end
 
         attr_reader :categories
 
-        # @param meta [Bluebook::Chapter] the language's own assembled
-        #   "Bluebook" chapter
+        # @param meta [Bluebook::Declaration] the language's own assembled
+        #   "Bluebook" bluebook
         def initialize(meta)
           @categories = {}
           meta.aggregates.each do |aggregate|
@@ -108,7 +108,7 @@ module Hecks
           {
             name:           aggregate.hecks_name,
             declare:        declare&.hecks_name,
-            parent:         owner || parent&.type&.target_name,
+            parent:         owner || parent&.target_name,
             parent_key:     owner ? "aggregate" : parent&.name&.to_s,
             # Read from the language, not restated: a hand-written join here
             # could disagree with the runtime's own by even one separator.

data/lib/hecks/bluebook/meta_validator/readings/fields.rb

@@ -69,16 +69,16 @@ module Hecks
           def points_at(row, aggregate_id)
             return nil unless row.reference?
 
-            # Built the same way an aggregate id itself is built (chapter +
+            # Built the same way an aggregate id itself is built (bluebook +
             # name), because `repository.find` resolves against that same id.
-            Naming.identity([aggregate_id.split(Naming::IDENTITY_JOIN).first, row.type.target_name])
+            Naming.identity([aggregate_id.split(Naming::IDENTITY_JOIN).first, row.target_name])
           end
 
           # Self-describing so the type survives the round trip (bare `to_s`
           # can't tell 0.0 from a string); `nil` stays `nil`, a real answer.
           def encode_literal(value) = value.nil? ? nil : Literal.render(value)
 
-          # The inverse of `points_at`: strips the id's chapter prefix, joined
+          # The inverse of `points_at`: strips the id's bluebook prefix, joined
           # with `Naming::IDENTITY_JOIN` rather than the wire format's `::`.
           def reference_type(points_at_id) = "Reference<#{points_at_id.to_s.split(Naming::IDENTITY_JOIN).last}>"
 

data/lib/hecks/bluebook/meta_validator/reconstruction/heads.rb

@@ -2,7 +2,7 @@ module Hecks
   module Bluebook
     module MetaValidator
       class Reconstruction
-        # Rebuilds the heads of a chapter: an aggregate, its value objects and the entities
+        # Rebuilds the heads of a bluebook: an aggregate, its value objects and the entities
         # nested under it, each with its own commands and asks.
         module Heads
           private
@@ -34,7 +34,8 @@ module Hecks
             {
               invariants:       rules_in(row, :invariants),
               preconditions:    rules_in(row, :preconditions),
-              projected_fields: Array(row[:projected_fields]).map { |held| projected_field(held) }
+              projected_fields: Array(row[:projected_fields]).map { |held| projected_field(held) },
+              acknowledgements: Array(row[:acknowledgements]).map { |held| acknowledgement(held) }
             }
           end
 
@@ -80,9 +81,16 @@ module Hecks
               field:       field,
               default:     text(row[:state_start]),
               transitions: Array(row[:transitions]).map { |move| transition(move) },
-              marks:       Array(row[:marks]).map { |held| mark(held) }
+              marks:       marks_by_name(row[:marks])
             }
           end
+
+          # The one-row-per-state marks as the IR spells them: `name => states`, in declared order.
+          def marks_by_name(rows)
+            Array(rows).map { |held| mark(held) }
+                       .group_by { |held| held[:name] }
+                       .transform_values { |held| held.map { |row| row[:state] } }
+          end
         end
       end
     end

data/lib/hecks/bluebook/meta_validator/reconstruction/reading.rb

@@ -55,7 +55,7 @@ module Hecks
           # and a join read out of order names a different record.
           def identity_paths(row) = Array(row[:identified_by]).map { |part| text(part[:value]).to_s }
 
-          # The contexts one chapter names itself onto, in the order they were
+          # The contexts one bluebook names itself onto, in the order they were
           # attached — same shape identity_paths reads back, one level up.
           def attached_contexts(row) = Array(row[:attaches_to]).map { |part| text(part[:value]).to_s }