hecks 3.4.2 → 3.6.0

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

@@ -63,435 +63,37 @@ module Hecks
           interpret(parse(expr), state, attrs)
         end
 
-        # Branch order is the precedence order (`.length` first, sign tests before the rest).
-        #
-        # @param expr [String] the leaf expression text
-        # @return [Object] the parsed leaf node, or `Lookup` when nothing else matches
-        # rubocop:disable-next Metrics/AbcSize
-        # rubocop:disable-next Metrics/CyclomaticComplexity
-        # rubocop:disable-next Metrics/MethodLength
-        # rubocop:disable-next Metrics/PerceivedComplexity
-        def parse(expr)
-          expr = expr.to_s.strip
-
-          return Size.new(receiver: parse(Regexp.last_match(1))) if expr =~ /\A(.+)\.length\z/
-
-          return IntegerLiteral.new(value: Integer(expr, 10)) if expr.match?(/\A-?\d+\z/)
-          return FloatLiteral.new(value: Float(expr))         if expr.match?(/\A-?\d*\.\d+\z/)
-          return StringLiteral.new(value: expr[1..-2])        if quoted?(expr)
-          return BoolLiteral.new(value: true)                 if expr == "true"
-          return BoolLiteral.new(value: false)                if expr == "false"
-          return NilLiteral.new if expr == "nil"
-
-          elements = array_elements(expr)
-          return ArrayLiteral.new(elements: elements.map { |element| parse(element) }) if elements
-
-          arithmetic = split_addition(expr)
-          return Addition.new(left: parse(arithmetic[0]), right: parse(arithmetic[1])) if arithmetic
-
-          sign = match_suffix(expr, SIGN_TESTS)
-          return sign_test_node(sign) if sign
-
-          return Empty.new(receiver: parse(Regexp.last_match(1))) if expr =~ /\A(.+)\.empty\?\z/
-          return ToS.new(receiver: parse(Regexp.last_match(1)))   if expr =~ /\A(.+)\.to_s\z/
-
-          modulo = match_call(expr, ".modulo(")
-          return Modulo.new(receiver: parse(modulo[0]), divisor: parse(modulo[1])) if modulo
-
-          return Size.new(receiver: parse(Regexp.last_match(1))) if expr =~ /\A(.+)\.size\z/
-
-          if expr =~ %r{\A(.+)\.match\?\(/(.*)/([a-z]*)\)\z}m
-            return MatchesRegex.new(receiver: parse(Regexp.last_match(1)),
-                                    pattern:  Regexp.last_match(2),
-                                    flags:    Regexp.last_match(3))
-          end
-
-          return Presence.new(receiver: parse(Regexp.last_match(1)), negated: false) if expr =~ /\A(.+)\.present\?\z/
-          return Presence.new(receiver: parse(Regexp.last_match(1)), negated: true)  if expr =~ /\A(.+)\.blank\?\z/
-
-          return Assignment.new(receiver: parse(Regexp.last_match(1)), negated: false) if expr =~ /\A(.+)\.set\?\z/
-          return Assignment.new(receiver: parse(Regexp.last_match(1)), negated: true)  if expr =~ /\A(.+)\.unset\?\z/
-
-          if expr =~ /\A(.+)\.split\("([^"]*)"\)\z/
-            return Split.new(receiver:  parse(Regexp.last_match(1)),
-                             separator: Regexp.last_match(2))
-          end
-
-          return First.new(receiver: parse(Regexp.last_match(1))) if expr =~ /\A(.+)\.first\z/
-          return Last.new(receiver: parse(Regexp.last_match(1))) if expr =~ /\A(.+)\.last\z/
-
-          if expr =~ /\A(.+)\.start_with\?\("([^"]*)"\)\z/
-            return StartsWith.new(receiver:  parse(Regexp.last_match(1)),
-                                  substring: Regexp.last_match(2))
-          end
-
-          if expr =~ /\A(.+)\.end_with\?\("([^"]*)"\)\z/
-            return EndsWith.new(receiver:  parse(Regexp.last_match(1)),
-                                substring: Regexp.last_match(2))
-          end
-
-          block_opener = parse_block_opener(expr)
-          return block_opener if block_opener
-
-          Lookup.new(path: expr)
-        end
-
-        def sign_test_node(parts)
-          receiver, test = parts
-          symbol   = SIGN_TEST_OPERATORS.fetch(test)
-          operator = Evaluator::OPERATORS.find { |candidate| candidate.symbol == symbol }
-          SignTest.new(operator: operator, test: test, receiver: parse(receiver))
-        end
-
         # Evaluates a node `parse` produced against `state` and `attrs`.
         #
         # @return [Object] the value the node resolves to
         # @raise [EvaluationError] if the node type is unhandled or an operand is refused
-        # rubocop:disable-next Metrics/AbcSize
-        # rubocop:disable-next Metrics/CyclomaticComplexity
-        # rubocop:disable-next Metrics/MethodLength
         def interpret(node, state, attrs)
           case node
           when IntegerLiteral, FloatLiteral, StringLiteral, BoolLiteral then node.value
           when ArrayLiteral then node.elements.map { |element| interpret(element, state, attrs) }
           when NilLiteral then nil
-          when Addition
-            add(interpret(node.left, state, attrs), interpret(node.right, state, attrs))
-          when SignTest
-            apply_sign_test(node, interpret(node.receiver, state, attrs))
-          when Empty
-            emptiness_of(interpret(node.receiver, state, attrs))
-          when ToS
-            string_of(interpret(node.receiver, state, attrs))
-          when Modulo
-            apply_modulo(interpret(node.receiver, state, attrs), interpret(node.divisor, state, attrs))
-          when Size
-            size_of(interpret(node.receiver, state, attrs))
-          when MatchesRegex
-            matches_regex?(interpret(node.receiver, state, attrs), node.pattern, node.flags)
-          when Presence
-            present = !blank?(interpret(node.receiver, state, attrs))
-            node.negated ? !present : present
-          when Assignment
-            set = !interpret(node.receiver, state, attrs).nil?
-            node.negated ? !set : set
-          when Split
-            split_value(interpret(node.receiver, state, attrs), node.separator)
-          when Last
-            last_of(interpret(node.receiver, state, attrs))
-          when First
-            first_of(interpret(node.receiver, state, attrs))
-          when Find
-            found_of(node, interpret(node.receiver, state, attrs), state, attrs)
-          when StartsWith
-            starts_with?(interpret(node.receiver, state, attrs), node.substring)
-          when EndsWith
-            ends_with?(interpret(node.receiver, state, attrs), node.substring)
-          when BlockPredicate
-            evaluate_block_predicate(node, interpret(node.receiver, state, attrs), state, attrs)
-          when Lookup
-            lookup(node.path, state, attrs)
-          else
-            # A missing arm must raise; silently returning nil is the one wrong answer
-            # this grammar never allows.
-            raise EvaluationError, "no interpreter handles #{node.class} — add a case before parse can produce it"
-          end
-        end
-
-        def blank?(value)
-          return true if value.nil? || value == false
-
-          # Duck-typed: reaching across to Runtime::Value would couple the namespaces. A list
-          # is judged by its own emptiness, never coerced: `[0].to_h` would raise TypeError.
-          value = value.to_h if value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
-          case value
-          when String, Array, Hash then value.empty?
-          else false
+          when Addition then add(interpret(node.left, state, attrs), interpret(node.right, state, attrs))
+          when Lookup then lookup(node.path, state, attrs)
+          else interpret_on_receiver(node, state, attrs)
           end
         end
 
-        def matches_regex?(receiver_value, pattern, flags)
-          text = case receiver_value
-                 when String, Symbol, Integer, Float then receiver_value.to_s
-                 when NilClass then ""
-                 else
-                   raise EvaluationError, "match? expects a scalar, got #{receiver_value.class}"
-                 end
-
-          options = 0
-          options |= Regexp::IGNORECASE if flags.include?("i")
-          options |= Regexp::MULTILINE  if flags.include?("m")
-          options |= Regexp::EXTENDED   if flags.include?("x")
-
-          Regexp.new(pattern, options).match?(text)
-        rescue RegexpError => e
-          # A malformed pattern is an author mistake; refuse it as EvaluationError.
-          raise EvaluationError, "match? given an invalid pattern #{pattern.inspect} — #{e.message}"
-        end
-
-        def array_elements(expr)
-          return nil unless expr.start_with?("[") && expr.end_with?("]")
-
-          inner = expr[1..-2].strip
-          return [] if inner.empty?
+        # Resolves the node's receiver, then applies the operation `RECEIVER_OPERATIONS` names.
+        def interpret_on_receiver(node, state, attrs)
+          _, operation = RECEIVER_OPERATIONS.find { |klass, _| node.is_a?(klass) }
+          # A missing arm must raise; silently returning nil is the one wrong answer
+          # this grammar never allows.
+          raise EvaluationError, "no interpreter handles #{node.class} — add a case before parse can produce it" unless operation
 
-          elements = []
-          depth = 0
-          quote = nil
-          current = +""
-          inner.each_char do |char|
-            if quote
-              quote = nil if char == quote
-              current << char
-              next
-            end
-            case char
-            when '"', "'" then quote = char
-            when "[", "(" then depth += 1
-            when "]", ")" then depth -= 1
-            end
-            if char == "," && depth.zero?
-              elements << current.strip
-              current = +""
-            else
-              current << char
-            end
-          end
-          elements << current.strip
-          elements.reject(&:empty?)
+          operation.call(node, interpret(node.receiver, state, attrs), state, attrs)
         end
-
-        # Braces and brackets count toward depth like parens, so a `+` inside a block body
-        # or an array element is not this expression's own addition.
-        def split_addition(expr)
-          depth = 0
-          quote = nil
-
-          expr.each_char.with_index do |char, index|
-            if quote
-              quote = nil if char == quote
-            elsif ['"', "'"].include?(char)
-              quote = char
-            # `[`/`]` count too: an array element may hold its own top-level `+`.
-            elsif ["(", "{", "["].include?(char)
-              depth += 1
-            elsif [")", "}", "]"].include?(char)
-              depth -= 1
-            elsif char == "+" && depth.zero?
-              return [expr[0...index].strip, expr[(index + 1)..].strip]
-            end
-          end
-          nil
-        end
-
-        # Integer is signed 64-bit; a sum outside the range is an evaluation fault (C3.3, C3.4).
-        INT64_RANGE = (-(2**63))..((2**63) - 1)
-
-        def add(left, right)
-          lhs = require_number(left, "addition")
-          rhs = require_number(right, "addition")
-          sum = lhs + rhs
-          if sum.is_a?(Integer)
-            return sum if INT64_RANGE.cover?(sum)
-
-            raise EvaluationError, "addition overflowed: #{lhs} + #{rhs} does not fit in a 64-bit integer"
-          end
-          return sum if sum.finite?
-
-          raise EvaluationError, "addition overflowed: #{lhs} + #{rhs} is not a finite number"
-        end
-
-        def quoted?(expr)
-          return false if expr.length < 2
-
-          (expr.start_with?('"') && expr.end_with?('"')) ||
-            (expr.start_with?("'") && expr.end_with?("'"))
-        end
-
-        # Held equal to Vocabulary::SizedType by spec/vocabulary_conformance_spec.
-        SIZED_TYPES = Hecks::Vocabulary.fetch("SizedType")
-
-        def size_of(value)
-          return value.size if value.is_a?(Array) || value.is_a?(String) || value.is_a?(Hash)
-
-          raise EvaluationError, "size expects a list or string, got #{describe(value)}"
-        end
-
-        def emptiness_of(value)
-          return value.empty? if value.is_a?(Array) || value.is_a?(String) || value.is_a?(Hash)
-
-          raise EvaluationError, "empty? expects a list or string, got #{describe(value)}"
-        end
-
-        def split_value(value, separator)
-          raise EvaluationError, "split expects a string, got #{describe(value)}" unless value.is_a?(String)
-
-          value.split(separator)
-        end
-
-        def last_of(value)
-          return value.last if value.respond_to?(:last)
-
-          raise EvaluationError, "last expects a list, got #{describe(value)}"
-        end
-
-        def first_of(value)
-          return value.first if value.respond_to?(:first)
-
-          raise EvaluationError, "first expects a list, got #{describe(value)}"
-        end
-
-        def starts_with?(value, substring)
-          raise EvaluationError, "start_with? expects a string, got #{describe(value)}" unless value.is_a?(String)
-
-          value.start_with?(substring)
-        end
-
-        def ends_with?(value, substring)
-          raise EvaluationError, "end_with? expects a string, got #{describe(value)}" unless value.is_a?(String)
-
-          value.end_with?(substring)
-        end
-
-        # Held equal to Vocabulary::ToStringType by spec/vocabulary_conformance_spec.
-        TO_STRING_TYPES = Hecks::Vocabulary.fetch("ToStringType")
-
-        def string_of(value)
-          case value
-          when String then value
-          when Integer, Float, TrueClass, FalseClass then value.to_s
-          when NilClass then ""
-          else
-            raise EvaluationError, "to_s expects a scalar, got #{describe(value)}"
-          end
-        end
-
-        def match_suffix(expr, suffixes)
-          suffixes.each do |suffix|
-            marker = ".#{suffix}"
-            return [expr[0...-marker.length], suffix] if expr.end_with?(marker)
-          end
-          nil
-        end
-
-        def apply_sign_test(node, value)
-          number = numeric(value)
-          raise EvaluationError, "#{node.test} expects a number, got #{describe(value)}" unless number
-
-          Evaluator.apply(node.operator, number, 0)
-        end
-
-        # Finds the outermost `marker` call whose matching `)` ends `expr`. `rindex` would split
-        # nested `.modulo(` calls at the inner one, and a first match alone mis-parses chains.
-        def match_call(expr, marker)
-          start = 0
-          while (index = expr.index(marker, start))
-            close = matching_paren(expr, index + marker.length)
-            return [expr[0...index], expr[(index + marker.length)...close]] if close == expr.length - 1
-
-            start = index + 1
-          end
-          nil
-        end
-
-        def matching_paren(expr, start)
-          depth = 1
-          quote = nil
-          index = start
-          while index < expr.length
-            char = expr[index]
-            if quote
-              quote = nil if char == quote
-            elsif ['"', "'"].include?(char)
-              quote = char
-            elsif char == "("
-              depth += 1
-            elsif char == ")"
-              depth -= 1
-              return index if depth.zero?
-            end
-            index += 1
-          end
-          nil
-        end
-
-        # The zero-check reads the coerced divisor, not the raw value or a `to_i` truncation.
-        def apply_modulo(receiver_value, divisor_value)
-          receiver = require_number(receiver_value, "modulo")
-          divisor  = require_number(divisor_value, "modulo")
-          raise EvaluationError, "divided by 0" if divisor.zero?
-
-          receiver % divisor
-        end
-
-        def lookup(expr, state, attrs)
-          return unwrap_scalar(fetch(expr, state, attrs)) unless expr.include?(".")
-
-          head, *rest = expr.split(".")
-          unwrap_scalar(walk_path(fetch(head, state, attrs), rest))
-        end
-
-        # Walks dotted segments through a Hash-like value. `key?` picks the symbol or string
-        # spelling so a held `false` is not mistaken for an absent key.
-        def walk_path(value, segments)
-          segments.reduce(value) do |current, segment|
-            break nil unless current.respond_to?(:[])
-
-            if current.is_a?(Hash)
-              sym = segment.to_sym
-              current.key?(sym) ? current[sym] : current[segment]
-            else
-              begin
-                current[segment]
-              rescue TypeError
-                # `Array#[]` raises a raw TypeError for a String segment; refuse it instead.
-                raise EvaluationError,
-                      "cannot read #{segment.inspect} from #{describe(current)}"
-              end
-            end
-          end
-        end
-
-        # Unwraps a single-field value object to its scalar so `field == "literal"` works.
-        # Gated on the field count, not its name. Mirrors `impl Fielded for Json` in
-        # rust/src/kernel/json.rs; change both together.
-        def unwrap_scalar(value)
-          return value unless value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
-
-          if value.respond_to?(:value_object)
-            sole = value.value_object.sole_attribute
-            return sole ? value[sole.name] : value
-          end
-
-          hash = value.to_h
-          hash.size == 1 && hash.key?(:value) ? hash[:value] : value
-        end
-
-        def fetch(name, state, attrs)
-          key = name.to_sym
-          return attrs[key] if attrs.key?(key)
-          return state[key] if known?(state, key)
-
-          raise EvaluationError, "cannot resolve #{name.inspect} — no such attribute or argument"
-        end
-
-        def known?(state, key)
-          return state.key?(key) if state.respond_to?(:key?)
-
-          !state[key].nil?
-        end
-
-        def numeric(value)
-          value if value.is_a?(Integer) || value.is_a?(Float)
-        end
-
-        def require_number(value, operation)
-          numeric(value) ||
-            raise(EvaluationError, "#{operation} expects a number, got #{describe(value)}")
-        end
-
-        def describe(value) = Rendering.describe(value)
       end
     end
   end
 end
+
+require_relative "resolver/scanning"
+require_relative "resolver/lookups"
+require_relative "resolver/parsing"
+require_relative "resolver/values"
+require_relative "resolver/operations"

data/lib/hecks/bluebook/{hexagon.rb → hecksagon.rb}

@@ -1,4 +1,5 @@
-require_relative "behaviour/hexagon"
+require_relative "behaviour/hecksagon"
+require_relative "keyword_fields"
 require_relative "../ir"
 
 module Hecks
@@ -54,6 +55,11 @@ module Hecks
 
       attr_reader :domain, :binds, :subscriptions, :attachments, :translates
 
+      # Every optional keyword and what it holds when the declaration omits it.
+      FIELD_DEFAULTS = {
+        binds: [], subscriptions: [], attachments: [], bounded: false, translates: []
+      }.freeze
+
       # @param domain [String, Symbol] the domain this hecksagon wires
       # @param binds [Array<Bluebook::Bind>] the declared adapter binds
       # @param subscriptions [Array<String, Symbol>] the external events this domain
@@ -63,14 +69,11 @@ module Hecks
       # @param bounded [Boolean] whether this chapter is an explicit bounded context
       #   (consumer-owned; `attaches` marks attached chapters bounded on the registry instead)
       # @param translates [Array<String>] names of `translates` ACL blocks declared here
-      def initialize(domain:, binds: [], subscriptions: [], attachments: [], bounded: false,
-                     translates: [])
+      def initialize(domain:, **given)
+        KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
         @domain             = domain.to_s
-        @binds              = binds
-        @subscriptions      = subscriptions
-        @attachments        = attachments
-        @bounded            = bounded ? true : false
-        @translates         = Array(translates).map(&:to_s)
+        @bounded            = @bounded ? true : false
+        @translates         = Array(@translates).map(&:to_s)
       end
 
       # Says whether this hecksagon marked its own chapter `bounded`.
@@ -107,6 +110,11 @@ module Hecks
 
       attr_reader :domain, :realm, :latest, :settings, :default_database, :default_adapter
 
+      # Every optional keyword and what it holds when the declaration omits it.
+      FIELD_DEFAULTS = {
+        realm: nil, latest: nil, settings: {}, default_database: nil, default_adapter: nil
+      }.freeze
+
       # @param domain [String, Symbol] the domain this world configures
       # @param realm [String, Symbol, nil] the declared realm/version marker, or `nil`
       #   if none is declared
@@ -119,13 +127,13 @@ module Hecks
       #   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
-      def initialize(domain:, realm: nil, latest: nil, settings: {}, default_database: nil, default_adapter: nil)
+      def initialize(domain:, **given)
+        KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
         @domain           = domain.to_s
-        @realm            = realm&.to_s
-        @latest           = latest&.to_s
-        @settings         = settings
-        @default_database = default_database&.to_s
-        @default_adapter  = default_adapter&.to_s
+        @realm            = @realm&.to_s
+        @latest           = @latest&.to_s
+        @default_database = @default_database&.to_s
+        @default_adapter  = @default_adapter&.to_s
       end
     end
   end

data/lib/hecks/bluebook/keyword_fields.rb

@@ -0,0 +1,42 @@
+module Hecks
+  module Bluebook
+    # The optional keywords of a wide IR constructor, held as a default table instead of a
+    # signature, so the constructor names only its required keywords and stays short.
+    #
+    # A constructor declares `FIELD_DEFAULTS`, takes `name:, **given`, and calls `fill` then
+    # `assign`. An unknown keyword raises `ArgumentError`, as a literal signature would.
+    module KeywordFields
+      # Merges the caller's keywords over the defaults, giving each omitted keyword its own copy
+      # of the default so a default `[]` or `{}` is never shared between instances.
+      #
+      # @param given [Hash{Symbol => Object}] the optional keywords the caller passed
+      # @param defaults [Hash{Symbol => Object}] every accepted optional keyword and its default
+      # @return [Hash{Symbol => Object}] one entry per accepted keyword
+      # @raise [ArgumentError] when `given` carries a keyword `defaults` does not name
+      def self.fill(given, defaults)
+        unknown = given.keys - defaults.keys
+        reject_unknown(unknown) unless unknown.empty?
+
+        defaults.to_h { |key, default| [key, given.fetch(key) { default.dup }] }
+      end
+
+      # Stores each field as the instance variable of the same name.
+      #
+      # @param target [Object] the instance being built
+      # @param fields [Hash{Symbol => Object}] the filled keywords
+      # @return [void]
+      def self.assign(target, fields)
+        fields.each { |key, value| target.instance_variable_set(:"@#{key}", value) }
+      end
+
+      # @param unknown [Array<Symbol>] the keywords no default names
+      # @raise [ArgumentError] always, worded as Ruby words a literal signature's refusal
+      def self.reject_unknown(unknown)
+        plural = "s" if unknown.size > 1
+        names = unknown.map(&:inspect).join(", ")
+        raise ArgumentError, "unknown keyword#{plural}: #{names}"
+      end
+      private_class_method :reject_unknown
+    end
+  end
+end

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

@@ -34,13 +34,14 @@ module Hecks
 
         def judge!
           send_to("Adapter::Adapter.Declare", @adapter.name, name: v(@adapter.name), port: v(@adapter.port))
+          add_all("AddField", @adapter.fields)
+          add_all("AddSecret", @adapter.secrets)
+        end
 
-          Array(@adapter.fields).each do |field|
-            send_to("Adapter::Adapter.AddField", @adapter.name, name: @adapter.name, value: v(field))
-          end
-
-          Array(@adapter.secrets).each do |secret|
-            send_to("Adapter::Adapter.AddSecret", @adapter.name, name: @adapter.name, value: v(secret))
+        # Offers one `verb` per value, each addressed to the adapter by name.
+        def add_all(verb, values)
+          Array(values).each do |value|
+            send_to("Adapter::Adapter.#{verb}", @adapter.name, name: @adapter.name, value: v(value))
           end
         end
       end

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

@@ -0,0 +1,99 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class Judge
+        # What one cell of an appended list is offered as: an attribute's type as the id of the
+        # value object it names, a reference as the head it points at, a default as a literal.
+        module Cells
+          private
+
+          # An entity has no value objects of its own; its attributes
+          # resolve against its enclosing aggregate's pool, so the root
+          # aggregate id (`parent_id`, not the direct parent) is what this
+          # returns for it.
+          def owning_aggregate_ref(category, id, parent_id)
+            category == "Entity" ? parent_id : id
+          end
+
+          # An attribute's type is offered as the id of the value object it
+          # names, so "attributes must use value-object types" is enforced
+          # by reference resolution rather than a predicate — for an
+          # entity's own attributes too, since an entity is its own root.
+          def cell(category, item, append, field)
+            value = row_value(item.row, field)
+            # A default keeps its type by being written as a literal (0.0,
+            # not "0.0"): the language holds it as text, and text alone forgets.
+            return encode_literal(value) if field == :default
+            return value unless field == :type
+            # A reference names another head wherever it's written (on a
+            # head, a command, a piece, or an ask), so it's offered as that
+            # head's id in all four; only a head's own attributes further
+            # qualify a plain type into a value object's id.
+            return points_at(item.row, item.id) if append.verb == "Reference"
+            return value unless attribute_list?(category, item.list_name)
+
+            Naming.identity([owning_aggregate_id(item.owner_id, value), value])
+          end
+
+          # A head's own attributes (an aggregate's, or an entity's own
+          # root). Every other "attributes" list belongs to something that
+          # isn't a head, so a type written there is a name, not a reference.
+          def attribute_list?(category, list_name)
+            list_name.to_s == "attributes" && %w[Aggregate Entity].include?(category)
+          end
+
+          # A value object's type may be declared on a different aggregate
+          # in the same chapter; 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 }
+            return id unless local
+            return id if names?(local, value)
+
+            owner = @bluebook.aggregates.find { |aggregate| aggregate != local && names?(aggregate, value) }
+            return id unless owner
+
+            Naming.identity([@bluebook.name, owner.name])
+          end
+
+          # Checks both value objects and entities this aggregate declares:
+          # the caller already knows which verb it dispatches, not which
+          # collection to search, without re-deriving that here.
+          def names?(aggregate, value)
+            aggregate.value_objects.any? { |vo| vo.hecks_name == value } ||
+              aggregate.entities.any? { |entity| entity.hecks_name == value }
+          end
+
+          # The row itself decides which verb an attribute belongs to:
+          # Attribute for a value-object type, Reference<X> for another
+          # aggregate's head, Holds for an entity this aggregate declares.
+          # Each alternate carries its own field map — borrowing the
+          # primary's would dispatch `type:` where Reference declares
+          # `points_at:`.
+          def append_for(category, list_name, append, row, node)
+            return append unless list_name.to_s == "attributes"
+            return alternate(category, "Reference") || append if reference_row?(row)
+            return alternate(category, "Holds") || append if entity_row?(row, node)
+
+            append
+          end
+
+          def alternate(category, verb)
+            @plan.category(category).alternates.find { |append| append.verb == verb }
+          end
+
+          def reference_row?(row) = row.respond_to?(:reference?) && row.reference?
+
+          # Only a head declares pieces; since every attribute list reaches
+          # here now, `node` may be a command, a piece or an ask, none of
+          # which answer `entities`.
+          def entity_row?(row, node)
+            return false unless node.respond_to?(:entities)
+
+            Array(node.entities).any? { |entity| entity.hecks_name == row.type.to_s }
+          end
+        end
+      end
+    end
+  end
+end