hecks 4.0.0 → 6.0.0

data/lib/hecks/bench/environment.rb

@@ -6,6 +6,9 @@ module Hecks
     # Describes the machine and toolchain a benchmark ran on.
     # Each probe is best effort: a missing tool yields `"unknown"`, not an error.
     module Environment
+      # The total-memory line of `/proc/meminfo`, capturing its size in KiB.
+      MEMORY_TOTAL = /MemTotal:\s+(\d+)/
+
       module_function
 
       def describe
@@ -20,7 +23,8 @@ module Hecks
       # Read before and after a run to show whether something else was busy.
       def load_average
         text = RUBY_PLATFORM.include?("darwin") ? capture("sysctl", "-n", "vm.loadavg").delete("{}") : File.read("/proc/loadavg")
-        text.split.first.to_f.round(2)
+        one_minute = text.split.first
+        one_minute.to_f.round(2)
       rescue SystemCallError
         nil
       end
@@ -39,7 +43,7 @@ module Hecks
           if RUBY_PLATFORM.include?("darwin")
             capture("sysctl", "-n", "hw.memsize").to_i
           else
-            File.read("/proc/meminfo")[/MemTotal:\s+(\d+)/, 1].to_i * 1024
+            File.read("/proc/meminfo")[MEMORY_TOTAL, 1].to_i * 1024
           end
         bytes.zero? ? "unknown" : (bytes / (1024.0**3)).round(1)
       rescue SystemCallError

data/lib/hecks/bench/postgres_probe.rb

@@ -1,3 +1,5 @@
+require_relative "../text"
+
 module Hecks
   module Bench
     # Decides whether the Postgres targets can run at all.
@@ -12,7 +14,7 @@ module Hecks
       rescue LoadError
         "the `pg` gem is not installed"
       rescue PG::Error => e
-        "no Postgres server is reachable (#{e.message.lines.first.to_s.strip}); start one, or point " \
+        "no Postgres server is reachable (#{Text.first_line(e.message)}); start one, or point " \
         "PGHOST, PGPORT and PGUSER at one"
       end
 

data/lib/hecks/bench/report.rb

@@ -5,6 +5,9 @@ module Hecks
     # Renders a `Suite.call` result as Markdown or JSON.
     # The Markdown carries machine, counts and skips so a pasted table is never a bare number.
     module Report
+      # A digit followed by whole groups of three digits to the end: where a thousands comma goes.
+      THOUSANDS_BOUNDARY = /(\d)(?=(\d{3})+\z)/
+
       module_function
 
       def markdown(result)
@@ -36,7 +39,7 @@ module Hecks
         return "n/a" if value.nil?
 
         whole, fraction = format("%.#{places}f", value).split(".")
-        [whole.gsub(/(\d)(?=(\d{3})+\z)/, '\1,'), fraction].compact.join(".")
+        [whole.gsub(THOUSANDS_BOUNDARY, '\1,'), fraction].compact.join(".")
       end
 
       def environment_block(environment)

data/lib/hecks/bench/suite.rb

@@ -10,7 +10,13 @@ module Hecks
 
       # What one domain's measuring holds across its rounds: the binaries built so far, and each
       # target's run summaries.
-      Round = Struct.new(:workload, :config, :log, :binaries, :summaries)
+      Round = Struct.new(:workload, :config, :log, :binaries, :summaries) do
+        # @return [Integer] how many runs each target gets
+        def runs = config.runs
+
+        # @return [String] the name of the domain being measured
+        def domain_name = workload.name
+      end
 
       module_function
 
@@ -82,8 +88,8 @@ module Hecks
       def measure_target(round, target, index)
         summary = measure_once(round.workload, target, round.config, round.binaries).summary
         round.summaries[target] << summary
-        position = "run #{index + 1}/#{round.config.runs}"
-        round.log.puts progress_line("#{round.workload.name} #{target}", position, summary)
+        position = "run #{index + 1}/#{round.runs}"
+        round.log.puts progress_line("#{round.domain_name} #{target}", position, summary)
       end
 
       def progress_line(label, position, summary)

data/lib/hecks/bluebook/acknowledgements.rb

@@ -0,0 +1,81 @@
+module Hecks
+  module Bluebook
+    # The findings a declaration may acknowledge, and the rule an acknowledgement must meet: a
+    # reason, and a kind the check really emits (ADR 0150).
+    module Acknowledgements
+      # The finding kinds an aggregate may acknowledge.
+      AGGREGATE_KINDS = %i[large_aggregate key_by_value orphaned_reference].freeze
+
+      # The kinds that are reported once per attribute or per referenced aggregate, so an
+      # acknowledgement of one names which (`of:`): the attribute for `key_by_value`, the
+      # referenced aggregate for `orphaned_reference`.
+      SUBJECT_KINDS = %i[key_by_value orphaned_reference].freeze
+
+      # The finding kinds a context-map relationship may acknowledge: those about the relationship
+      # itself. An undeclared coupling or a separate-ways breach has no relationship to carry the
+      # allowance; the fix is to declare one.
+      RELATIONSHIP_KINDS = %i[relationship_kind_mismatch conformist_translates unpublished_dependency
+                              unused_relationship redundant_relationship].freeze
+
+      # @param owner [String] the declaration carrying the word, for the message
+      # @param finding [Symbol, String] the kind being acknowledged
+      # @param reason [Object] why; must be non-blank text
+      # @param among [Array<Symbol>] the kinds the owner may acknowledge
+      # @return [Symbol] the kind, once it passes
+      # @raise [DSL::Malformed] if the kind is not among those, or the reason is blank
+      def self.kind!(owner, finding, reason, among: AGGREGATE_KINDS)
+        kind = finding.to_s.to_sym
+        refuse_kind!(owner, kind, among) unless among.include?(kind)
+        refuse_reason!(owner, kind) unless reason.is_a?(String) && !reason.strip.empty?
+        kind
+      end
+
+      # @param owner [String] the declaration carrying the word, for the message
+      # @param kind [Symbol] the kind being acknowledged
+      # @param subject [Symbol, String, nil] what `of:` named
+      # @return [String, nil] the subject as text, once the kind and subject agree
+      # @raise [DSL::Malformed] if a per-subject kind names none, or another kind names one
+      def self.subject!(owner, kind, subject)
+        named = subject.to_s unless subject.nil? || subject.to_s.strip.empty?
+        return named if SUBJECT_KINDS.include?(kind) == !named.nil?
+
+        raise DSL::Malformed, subject_message(owner, kind)
+      end
+
+      # @return [String] why the subject and the kind disagree
+      def self.subject_message(owner, kind)
+        if SUBJECT_KINDS.include?(kind)
+          "#{owner} acknowledges :#{kind} without saying which — add `of:` naming the " \
+            "#{kind == :key_by_value ? "attribute" : "referenced aggregate"} it is for"
+        else
+          "#{owner} acknowledges :#{kind} with `of:`, which names a subject only :key_by_value and " \
+            ":orphaned_reference have"
+        end
+      end
+
+      # @raise [DSL::Malformed] always, naming the kinds that can be acknowledged
+      def self.refuse_kind!(owner, kind, among)
+        raise DSL::Malformed,
+              "#{owner} acknowledges :#{kind}, a finding model_check does not report here — " \
+              "the kinds are #{among.map(&:inspect).join(", ")}"
+      end
+
+      # @raise [DSL::Malformed] always, saying a reason is required
+      def self.refuse_reason!(owner, kind)
+        raise DSL::Malformed,
+              "#{owner} acknowledges :#{kind} without a reason in text — an allowance says why it is allowed"
+      end
+
+      # @param aggregate [Bluebook::Aggregate] the aggregate to read
+      # @param kind [Symbol] a finding kind
+      # @param subject [Symbol, String, nil] the attribute or referenced aggregate, for the kinds
+      #   reported once per subject
+      # @return [Boolean] whether the aggregate acknowledges that kind (for that subject)
+      def self.held?(aggregate, kind, subject: nil)
+        aggregate.acknowledgements.any? do |held|
+          held.finding.to_sym == kind && (subject.nil? || held.subject.to_s == subject.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/aggregate.rb

@@ -8,7 +8,11 @@ module Hecks
     # `reference` is the local reference attribute to walk; `remote_field` the target's scalar.
     ProjectedField = Struct.new(:name, :reference, :remote_field, keyword_init: true)
 
-    # An aggregate: carries its own identity and sits in the owner chain below its chapter.
+    # A finding the aggregate means, with the reason it is allowed (`acknowledges :kind, "why"`).
+    # `subject` names the one attribute or referenced aggregate a finding about several is for.
+    Acknowledgement = Struct.new(:finding, :reason, :subject, keyword_init: true)
+
+    # An aggregate: carries its own identity and sits in the owner chain below its bluebook.
     # The holding half only; `Behaviour::Aggregate` carries what the declaration cannot derive.
     class Aggregate
       include Construct
@@ -37,18 +41,23 @@ module Hecks
         queries:          many(:queries),
         # Additive: domains that declare no port emit `ports: []`; no existing key moves.
         ports:            many(:ports),
-        provenance:       :provenance
+        provenance:       :provenance,
+        # Additive: an aggregate that acknowledges no finding emits `acknowledgements: []`.
+        acknowledgements: lambda {
+          acknowledgements.map { |held| { finding: held.finding.to_s, subject: held.subject.to_s, reason: held.reason } }
+        }
       )
 
       attr_reader :name, :description, :attributes, :value_objects, :commands, :invariants, :preconditions,
                   :projected_fields, :identified_by, :identity_paths, :identity_heads, :lifecycle,
-                  :entities, :queries, :policies, :ports, :reference_targets, :provenance
+                  :entities, :queries, :policies, :ports, :reference_targets, :provenance,
+                  :acknowledgements
 
       # Every optional field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
         description: nil, attributes: [], value_objects: [], commands: [], invariants: [],
         preconditions: [], projected_fields: [], identified_by: [], lifecycle: nil, entities: [],
-        queries: [], policies: [], ports: [], reference_targets: [], provenance: nil
+        queries: [], policies: [], ports: [], reference_targets: [], provenance: nil, acknowledgements: []
       }.freeze
 
       # Assigns the declared fields, then `settle` derives identity, name indexes and owner stamps.

data/lib/hecks/bluebook/ask_resolution.rb

@@ -24,13 +24,13 @@ module Hecks
 
       module_function
 
-      # Resolves one ask policy against a chapter's aggregates and their declared ports.
+      # Resolves one ask policy against a bluebook's aggregates and their declared ports.
       #
-      # @param chapter [Bluebook::Chapter] the chapter the policy is declared in
+      # @param bluebook [Bluebook::Declaration] the bluebook the policy is declared in
       # @param policy [Bluebook::Policy] a policy that `asks?`
       # @return [Outcome] the verb, or the problem
-      def call(chapter, policy)
-        aggregate = event_aggregate(chapter, policy)
+      def call(declaration, policy)
+        aggregate = event_aggregate(declaration, policy)
         return no_aggregate(policy) unless aggregate
 
         found = picked(candidates(aggregate, policy.ask))
@@ -50,14 +50,14 @@ module Hecks
         found.size > 1 && !chosen.empty? ? chosen : found
       end
 
-      # Binds every ask policy of a chapter that resolves, leaving the rest for the boot gate and
+      # Binds every ask policy of a bluebook that resolves, leaving the rest for the boot gate and
       # `model_check` to name.
       #
-      # @param chapter [Bluebook::Chapter] the chapter whose policies to resolve
+      # @param bluebook [Bluebook::Declaration] the bluebook whose policies to resolve
       # @return [void]
-      def bind_resolved(chapter)
-        chapter.policies.select(&:asks?).each do |policy|
-          outcome = call(chapter, policy)
+      def bind_resolved(declaration)
+        declaration.policies.select(&:asks?).each do |policy|
+          outcome = call(declaration, policy)
           policy.resolve_ask!(outcome.verb) if outcome.resolved?
         end
       end
@@ -65,14 +65,14 @@ module Hecks
       # Marks the named ask on the named port as the one policies reach, for `ask_via`, and
       # re-binds every ask the pick settles.
       #
-      # @param chapter [Bluebook::Chapter, nil] the chapter the aggregate belongs to
+      # @param bluebook [Bluebook::Declaration, nil] the bluebook the aggregate belongs to
       # @param aggregate_name [String] the aggregate declaring the port
       # @param name [String, Symbol] the ask's declared name
       # @param port [String, Symbol] the port whose ask is picked
       # @return [void]
       # @raise [Bluebook::DSL::Malformed] if no such ask is declared on that port yet
-      def pick!(chapter, aggregate_name, name, port)
-        held = chapter&.aggregate(aggregate_name)&.port(port)
+      def pick!(declaration, aggregate_name, name, port)
+        held = declaration&.aggregate(aggregate_name)&.port(port)
         operation = held&.operation(name)
         unless operation
           raise DSL::Malformed, "#{aggregate_name}.ask_via #{name.to_s.inspect}, port: #{port.to_s.inspect} " \
@@ -80,18 +80,18 @@ module Hecks
         end
 
         operation.choose!
-        bind_resolved(chapter)
+        bind_resolved(declaration)
       end
 
       # The aggregate whose event the policy reacts to: the one the event is qualified with, or
       # the one whose commands emit it when the event is written bare.
       #
       # @return [Bluebook::Aggregate, nil]
-      def event_aggregate(chapter, policy)
+      def event_aggregate(declaration, policy)
         qualifier = policy.event_qualifier
-        return chapter.aggregate(Naming.demodulise(qualifier)) if qualifier
+        return declaration.aggregate(Naming.demodulise(qualifier)) if qualifier
 
-        chapter.aggregates.find do |aggregate|
+        declaration.aggregates.find do |aggregate|
           aggregate.commands.any? { |command| Array(command.emits).include?(policy.event_name) }
         end
       end
@@ -108,7 +108,7 @@ module Hecks
       def no_aggregate(policy)
         Outcome.new(problem: :no_aggregate,
                     detail:  "#{policy.name}'s ask #{policy.ask.to_sym.inspect} reacts to " \
-                             "#{policy.on_event.inspect}, whose aggregate this chapter does not declare")
+                             "#{policy.on_event.inspect}, whose aggregate this bluebook does not declare")
       end
 
       def unmatched(aggregate, policy)

data/lib/hecks/bluebook/assembly/aggregate_assembly.rb

@@ -31,7 +31,7 @@ module Hecks
             entities:          Array(@row[:entities]).map { |piece| entity(piece) },
             queries:           build_all("Query", @row[:queries]),
             lifecycle:         lifecycle_of(@row),
-            # Policies live on the chapter, which is what `PolicyInterpreter` reads.
+            # Policies live on the bluebook, which is what `PolicyInterpreter` reads.
             policies:          [],
             reference_targets: reference_targets(Array(@row[:attributes]).map { |field| Marks.attribute(field) })
           }
@@ -43,7 +43,7 @@ module Hecks
 
         # Read from attributes, not commands: a command's self-references are not targets.
         def reference_targets(fields)
-          fields.select(&:reference?).map { |field| field.type.target_name }
+          fields.select(&:reference?).map(&:target_name)
         end
 
         # Recurses, so entities nest to any depth (ADR 0026).
@@ -84,7 +84,7 @@ module Hecks
             field:       declared[:field],
             default:     declared[:default],
             transitions: transitions(Array(declared[:transitions])),
-            marks:       marks(Array(declared[:marks]))
+            marks:       marks(declared[:marks])
           )
         end
 
@@ -98,9 +98,12 @@ module Hecks
               end
         end
 
-        # Regroups the one-row-per-state marks back into `name => states`, in declared order.
+        # Regroups the one-row-per-state marks back into `name => states`, in declared order. The
+        # IR's own `to_h` already carries them as `name => states`, which passes through.
         def marks(rows)
-          rows.group_by { |held| held[:name].to_s }.transform_values { |held| held.map { |row| row[:state].to_s } }
+          return rows.to_h { |name, states| [name.to_s, Array(states).map(&:to_s)] } if rows.is_a?(Hash)
+
+          Array(rows).group_by { |held| held[:name].to_s }.transform_values { |held| held.map { |row| row[:state].to_s } }
         end
 
         def from_of(froms)

data/lib/hecks/bluebook/assembly/contracts/structure.rb

@@ -1,11 +1,11 @@
 module Hecks
   module Bluebook
     class Assembly
-      # The contracts for the chapter, aggregate, command and value object;
+      # The contracts for the bluebook, aggregate, command and value object;
       # `CONTRACTS` merges every group.
       STRUCTURE = {
         "Bluebook"    => Contract.new(
-          holder: Chapter, make: :new,
+          holder: Declaration, make: :new,
           fields: {
             name:              [:name,           :plain],
             version:           [:version,        :plain],
@@ -32,13 +32,14 @@ module Hecks
             preconditions:    [:preconditions, [:each, :given]],
             # The local half of `projects :name, from: "reference.remote_field"` (ADR 0025).
             projected_fields: [:projected_fields, [:each, :projected_field]],
-            provenance:       [:provenance, :plain]
+            provenance:       [:provenance, :plain],
+            acknowledgements: [:acknowledgements, [:each, :acknowledgement]]
           },
           rows: { transitions: :transition_rows, marks: :mark_rows, value_objects: :value_object_names,
                   identified_by: :identity_rows },
           reads: { identified_by: [:each, :identity_path], attributes: [:each_with_id, :attribute],
                    invariants: [:each, :rule], preconditions: [:each, :rule],
-                   projected_fields: [:each, :projected_field] },
+                   projected_fields: [:each, :projected_field], acknowledgements: [:each, :acknowledgement] },
           derived: {
             position:      :walk,
             state_field:   [:folded, :lifecycle, :field],
@@ -54,6 +55,7 @@ module Hecks
           fields: {
             name:       [:name,       :plain],
             role:       [:role,       :plain],
+            roles:      [:roles,      :plain],
             goal:       [:goal,       :plain],
             references: [:references, :plain],
             attributes: [:attributes, [:each, :shape_field]],
@@ -64,12 +66,14 @@ module Hecks
             emits:      [:emits,      :plain],
             # Lifecycle state as a command guard: one state, an array, or nil (ADR 0025).
             from:       [:from,       :plain],
-            provenance: [:provenance, :plain]
+            provenance: [:provenance, :plain],
+            idempotent: [:idempotent, :plain]
           },
           rows: { mutations: :mutation_rows },
           reads: { attributes: [:each, :shape_field], givens: [:each, :rule], ensures: [:each, :rule],
-                  needs: [:each, :need], mutations: [:call, :mutations], emits: :names, provenance: :provenance,
-                  from: :from },
+                  needs: [:each, :need], mutations: [:call, :mutations], emits: :names, roles: :names,
+                  provenance: :provenance,
+                  from: :from, idempotent: :idempotent? },
           derived: { position: :walk }
         ),
 

data/lib/hecks/bluebook/assembly/marks.rb

@@ -4,13 +4,16 @@ module Hecks
       # Reads the leaf shapes of an assembly's `to_h` export back into IR objects.
       # Each method inverts one textual spelling, so types are recovered, not just strings.
       module Marks
+        # A reference type as `to_s` spells it, capturing the target: "Reference<Customer>".
+        REFERENCE_SPELLING = /\AReference<(.+)>\z/
+
         module_function
 
         # `Attribute#to_h` spells a type with `to_s`, so a reference arrives as
         # "Reference<Customer>" and has to become an edge again.
         def attribute(field)
           type = field[:type].to_s
-          target = type[/\AReference<(.+)>\z/, 1]
+          target = type[REFERENCE_SPELLING, 1]
 
           Attribute.new(name: field[:name], type: target ? Reference.new(target) : type, **attribute_options(field))
         end
@@ -73,6 +76,12 @@ module Hecks
                              remote_field: row[:remote_field].to_sym)
         end
 
+        # One acknowledged finding: the kind comes back a Symbol, the reason stays text.
+        def acknowledgement(row)
+          subject = row[:subject].to_s
+          Acknowledgement.new(finding: row[:finding].to_sym, reason: row[:reason], subject: (subject unless subject.empty?))
+        end
+
         # `Mutation#to_h` branches on the operation, so this does too.
         # An append binds several fields, each an argument (a Symbol) or a literal.
         def mutation(change)

data/lib/hecks/bluebook/assembly/scalars.rb

@@ -7,6 +7,12 @@ module Hecks
       # is quoted so it stays a String. The Rust parser reads a cell the same way (`cell_value`
       # in `parse/value_object.rs`).
       module Scalars
+        # An optionally negative whole number, and nothing else.
+        INTEGER = /\A-?\d+\z/
+
+        # An optionally negative decimal with digits both sides of the point, and nothing else.
+        DECIMAL = /\A-?\d+\.\d+\z/
+
         module_function
 
         # @param value [Object] a cell as the builder holds it
@@ -28,8 +34,8 @@ module Hecks
           return Literal.unquote(text) if Literal.quoted?(text)
           return true       if text == "true"
           return false      if text == "false"
-          return text.to_i  if text.match?(/\A-?\d+\z/)
-          return text.to_f  if text.match?(/\A-?\d+\.\d+\z/)
+          return text.to_i  if text.match?(INTEGER)
+          return text.to_f  if text.match?(DECIMAL)
 
           text
         end

data/lib/hecks/bluebook/assembly/specializer.rb

@@ -8,8 +8,8 @@ module Hecks
 
         # Finds a construct by name — an aggregate, or an entity nested anywhere
         # under one (recursively, since an entity like Dispatch nests two deep).
-        def construct_for(chapter, name)
-          chapter.aggregate(name) || chapter.aggregates.filter_map { |a| find_entity(a, name) }.first
+        def construct_for(declaration, name)
+          declaration.aggregate(name) || declaration.aggregates.filter_map { |a| find_entity(a, name) }.first
         end
 
         # Searches a construct's own entities, recursively, for one by name.

data/lib/hecks/bluebook/assembly.rb

@@ -1,25 +1,25 @@
 module Hecks
   module Bluebook
     # Builds the runtime graph (aggregates, read models, process managers) from
-    # a chapter's declared hash — the pure inverse of `Chapter#to_h`.
+    # a bluebook's declared hash — the pure inverse of `Bluebook#to_h`.
     class Assembly
-      # Builds the graph the runtime runs from one chapter's declared hash.
+      # Builds the graph the runtime runs from one bluebook's declared hash.
       #
-      # @param declaration [Hash{Symbol => Object}] a chapter's declarations, in the
-      #   shape `Chapter#to_h` spells
-      # @return [Bluebook::Chapter] the assembled chapter, with its aggregates, read
+      # @param declaration [Hash{Symbol => Object}] a bluebook's declarations, in the
+      #   shape `Bluebook#to_h` spells
+      # @return [Bluebook::Declaration] the assembled bluebook, with its aggregates, read
       #   models and process managers built and wired
       def self.call(declaration) = new(declaration).bluebook
 
-      # @param declaration [Hash{Symbol => Object}] a chapter's declarations, in the
-      #   shape `Chapter#to_h` spells
+      # @param declaration [Hash{Symbol => Object}] a bluebook's declarations, in the
+      #   shape `Bluebook#to_h` spells
       def initialize(declaration)
         @declaration = declaration
       end
 
-      # Assembles this instance's declared hash into the chapter's runtime graph.
+      # Assembles this instance's declared hash into the bluebook's runtime graph.
       #
-      # @return [Bluebook::Chapter] the assembled chapter, with its aggregates, read
+      # @return [Bluebook::Declaration] the assembled bluebook, with its aggregates, read
       #   models and process managers built and wired
       def bluebook
         aggregates = Array(@declaration[:aggregates]).map { |row| AggregateAssembly.new(row).aggregate }
@@ -36,7 +36,7 @@ module Hecks
 
       private
 
-      # Hoists each reaction onto the chapter (for the runtime) and also back onto
+      # Hoists each reaction onto the bluebook (for the runtime) and also back onto
       # the aggregate head that declared it, per the language's own record of which.
       def reactions(aggregates)
         Array(@declaration[:policies]).map { |row| Build.call("Policy", row) }.each do |reaction|

data/lib/hecks/bluebook/behaviour/aggregate.rb

@@ -9,8 +9,9 @@ module Hecks
         include Identified
         include Indexed
         include Owns
+        include Stateful
 
-        # An aggregate joins its chapter's namespace with "::" ("Pizzas::Pizza");
+        # An aggregate joins its bluebook's namespace with "::" ("Pizzas::Pizza");
         # everything else joins its owner with ".".
         #
         # @return [String] the literal string `"::"`

data/lib/hecks/bluebook/behaviour/attribute.rb

@@ -18,6 +18,18 @@ module Hecks
         # @return [Boolean] whether this attribute's type is a `reference_to` another aggregate
         def reference? = @type.is_a?(Reference)
 
+        # The aggregate a `reference_to` attribute points at.
+        #
+        # @return [String, nil] the referenced aggregate's name, or `nil` when this is no reference
+        def target_name = (@type.target_name if reference?)
+
+        # The aggregate a `reference_to` attribute points at, resolved in its own bluebook.
+        #
+        # @return [Bluebook::Aggregate, nil] the target aggregate, or `nil` when this is no
+        #   reference or the target belongs to another domain
+        # @raise [Bluebook::DSL::Malformed] if the reference cannot say which aggregate declares it
+        def target_aggregate = (@type.resolve if reference?)
+
         # May this fact be left out? Required is the default; only a command enforces
         # this, since aggregate and value object attributes are not caller payloads.
         #

data/lib/hecks/bluebook/behaviour/command.rb

@@ -59,7 +59,7 @@ module Hecks
         def addressing_key_for(aggregate_name)
           return Naming.reference_key(aggregate_name) if references.to_s == aggregate_name.to_s
 
-          attributes.find { |attribute| attribute.reference? && attribute.type.target_name.to_s == aggregate_name.to_s }
+          attributes.find { |attribute| attribute.reference? && attribute.target_name.to_s == aggregate_name.to_s }
                     &.name
         end
       end