hecks 5.0.0 → 7.0.0

data/lib/hecks/bluebook/model_check/client_profile.rb

@@ -7,54 +7,20 @@ module Hecks
       #
       # Each rule names a bug that is still open; delete the rule when the bug is fixed.
       module ClientProfile
-        # Adapters whose Ruby class implements `query_read_model`, which is what
-        # makes `ReadModelInterpreter#project` take the native path. The spec
-        # checks this list against the adapter classes themselves.
-        NATIVE_READ_MODEL_ADAPTERS = %w[SqliteProjection].freeze
-
-        NATIVE_READ_MODEL_TRACKER = "docs/1.0-readiness.md (Known gaps at 1.0, item 2)".freeze
+        # The rule methods `call` runs, each answering `(bluebook, hecksagon)` with its findings.
+        # None is open. A rooted read model a projection answers natively is not refused:
+        # `Fuzzing::ProjectionAgreement` checks it against the in-process loop (ADR 0122).
+        RULES = [].freeze
 
         module_function
 
-        # Runs every client-profile rule over one chapter.
+        # Runs every client-profile rule over one bluebook.
         #
-        # @param bluebook [Bluebook::Chapter] the assembled chapter to check
-        # @param hecksagon [Bluebook::Hecksagon, nil] the chapter's sibling wiring file; without
-        #   one no aggregate is projected, so the native-read-model rule has nothing to find
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
+        # @param hecksagon [Bluebook::Hecksagon, nil] the bluebook's sibling wiring file
         # @return [Array<ModelCheck::Finding>] one error-severity finding per construct refused
         def call(bluebook, hecksagon: nil)
-          bluebook.read_models.flat_map do |model|
-            native_read_model_findings(model, hecksagon)
-          end
-        end
-
-        # Refuses a read model that the SQLite projection would answer natively.
-        #
-        # Mirrors the fork in `ReadModelInterpreter#project`: which path runs is only
-        # known at run time, so a model eligible here can still run in process.
-        #
-        # @param model [Bluebook::ReadModel] the read model to inspect
-        # @param hecksagon [Bluebook::Hecksagon, nil] the wiring holding the `projected_by` binds
-        # @return [Array<ModelCheck::Finding>] one finding, or `[]` when the model cannot be
-        #   pushed down
-        def native_read_model_findings(model, hecksagon)
-          return [] unless hecksagon && native_eligible?(model)
-
-          bind = hecksagon.binds_for(model.reference_target, Ports::Projection::VERB).first
-          return [] unless bind && NATIVE_READ_MODEL_ADAPTERS.include?(bind.adapter.to_s)
-
-          [finding(:client_native_read_model, model.name,
-                   "#{model.reference_target} is projected_by #{bind.adapter.inspect}, so this read model " \
-                   "is answered by SQL when the projection is current and by the in-process loop when it " \
-                   "is not, and nothing checks the two agree. Tracked in #{NATIVE_READ_MODEL_TRACKER}.")]
-        end
-
-        # Reports whether a model's shape sends it down the native path in `#project`.
-        #
-        # @param model [Bluebook::ReadModel] the read model to inspect
-        # @return [Boolean] true for a rooted model declaring no `group_by`, `count` or `median`
-        def native_eligible?(model)
-          !model.reference_target.nil? && model.group_by.empty? && !model.count? && !model.median_field
+          RULES.flat_map { |rule| public_send(rule, bluebook, hecksagon) }
         end
 
         # Builds one error-severity finding of this profile.

data/lib/hecks/bluebook/model_check/context_checks.rb

@@ -0,0 +1,97 @@
+require_relative "context_map_checks"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks over how contexts relate to each other: a `translates` has to listen to a context
+      # this hecksagon acknowledges, and no two contexts may depend on each other in a cycle.
+      module ContextChecks
+        include ContextMapChecks
+
+        # The edge kinds that couple two contexts at run time. A shared kernel merges in-process, so
+        # two contexts attaching each other is a different question and is left out.
+        COUPLING_KINDS = %w[customer_supplier acl].freeze
+
+        # A `translates` reacts to a foreign event, so the context that owns that event has to be
+        # attached or subscribed to, as an `across` policy's target does.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose policies are checked
+        # @param hecksagon [Bluebook::Hecksagon, nil] the bluebook's own wiring
+        # @param owners [Hash{String => Array<String>}, nil] each aggregate name to the contexts
+        #   that declare it; nothing is checked without it
+        # @return [Array<Finding>] one finding per translates whose source is not acknowledged
+        def translates_source_findings(bluebook, hecksagon, owners)
+          return [] unless hecksagon && owners
+
+          translated = bluebook.policies.select { |policy| hecksagon.translates.include?(policy.name.to_s) }
+          translated.filter_map { |policy| unacknowledged_source_finding(bluebook, policy, hecksagon, owners) }
+        end
+
+        # The aggregate name is not unique across contexts, so a source counts as acknowledged when
+        # any context that declares it is.
+        def unacknowledged_source_finding(bluebook, policy, hecksagon, owners)
+          sources = Array(owners[Naming.qualifier(policy.on_event)]).map(&:to_s)
+          return if sources.empty? || sources.include?(bluebook.name.to_s)
+          return if sources.any? { |source| acknowledged_source?(hecksagon, source) }
+
+          Finding.new(kind: :unacknowledged_source, severity: :error, subject: policy.name,
+                      message: unacknowledged_source_message(policy, sources))
+        end
+
+        # @return [String] what is wrong and the two ways to acknowledge the source
+        def unacknowledged_source_message(policy, sources)
+          "translates #{policy.on_event.inspect}, which #{sources.join(" or ")} owns, but " \
+            "nothing in this hecksagon acknowledges it — add attaches #{sources.first.inspect} " \
+            "or subscribe \"#{sources.first}.SomeEvent\""
+        end
+
+        # @return [Boolean] whether the hecksagon attaches the context or subscribes to its events
+        def acknowledged_source?(hecksagon, source)
+          hecksagon.attaches?(source) || hecksagon.subscriptions.any? { |event| Naming.qualifier(event) == source }
+        end
+
+        # Cycles are reported across the whole corpus: no one bluebook's check sees both directions.
+        #
+        # @param edges [Array<Hash>] `Projections::ContextRelationships.call`, for every registry
+        # @return [Array<Finding>] one warning per group of contexts that reach each other
+        def context_cycle_findings(edges)
+          cyclic_groups(coupling_graph(edges)).map do |group|
+            Finding.new(kind: :context_cycle, severity: :warning, subject: group.join(" <-> "),
+                        message: "these contexts depend on each other through across or translates: #{group.join(", ")}")
+          end
+        end
+
+        # @return [Hash{String => Array<String>}] each context to the contexts it depends on
+        def coupling_graph(edges)
+          edges.select { |edge| COUPLING_KINDS.include?(edge[:kind]) }
+               .each_with_object(Hash.new { |graph, node| graph[node] = [] }) do |edge, graph|
+            graph[edge[:from]] << edge[:to]
+          end
+        end
+
+        # Contexts that reach each other, grouped. A context with no way back is not in a cycle.
+        def cyclic_groups(graph)
+          reach = graph.keys.to_h { |node| [node, reachable_from(graph, node)] }
+          groups = reach.keys.map do |node|
+            ([node] + reach[node].select { |other| reach.fetch(other, []).include?(node) }).uniq.sort
+          end
+          groups.select { |group| group.size > 1 }.uniq
+        end
+
+        # @return [Array<String>] every context reachable by following dependencies from `start`
+        def reachable_from(graph, start)
+          seen = []
+          queue = graph.fetch(start, []).dup
+          until queue.empty?
+            node = queue.shift
+            next if seen.include?(node)
+
+            seen << node
+            queue.concat(graph.fetch(node, []))
+          end
+          seen
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/context_map_checks.rb

@@ -0,0 +1,158 @@
+require_relative "redundant_relationships"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks that hold a system's wiring to its declared context map (ADR 0135). The wiring
+      # is `Projections::ContextRelationships`' edges, each pointing from the context that depends
+      # to the one it depends on; the map's relationships run from upstream to downstream.
+      module ContextMapChecks
+        include RedundantRelationships
+
+        # The declared kinds each derived edge kind may implement. An attach and a subscription are
+        # `conformist` unless the map says another kind for the pair; `shared_kernel` is declared,
+        # never derived, since the wiring cannot tell a co-owned model from one taken as given.
+        IMPLEMENTS = {
+          "customer_supplier" => %i[customer_supplier],
+          "acl"               => %i[anticorruption_layer],
+          "shared_kernel"     => %i[conformist shared_kernel open_host],
+          "subscription"      => %i[conformist customer_supplier open_host]
+        }.freeze
+
+        # Kinds with no direction: either context may be the one that depends.
+        MUTUAL = %i[shared_kernel partnership].freeze
+
+        # What separates a context or aggregate from an event's own name: `Billing.InvoicePaid`.
+        QUALIFIER = /[.:]+/
+
+        # @param map [Bluebook::ContextMap, nil] the declared map; nothing is checked without one
+        # @param edges [Array<Hash>] `Projections::ContextRelationships.call`, for every registry
+        # @return [Array<Finding>] what the wiring does that the map does not allow, and what the
+        #   map declares that the wiring never uses
+        def context_map_findings(map, edges)
+          return [] unless map
+
+          held = map.implying(edges)
+          [*edges.flat_map { |edge| coupling_findings(held, edge) }, *unused_relationship_findings(map, edges),
+           *redundant_relationship_findings(map, edges)]
+        end
+
+        # @return [Array<Finding>] the findings for one derived edge
+        def coupling_findings(map, edge)
+          consumer = edge[:from]
+          supplier = edge[:to]
+          return [separate_ways_finding(edge)] if map.separate?(consumer, supplier)
+
+          declared = map.relationships_between(consumer, supplier)
+          return [undeclared_finding(edge, "no relationship is declared")] if declared.empty?
+
+          aligned = declared.select { |relationship| runs_from?(relationship, supplier, consumer) }
+          return [undeclared_finding(edge, reversed_note(declared))] if aligned.empty?
+
+          kind_findings(edge, aligned)
+        end
+
+        # @return [Array<Finding>] the kind and published-language findings for an aligned edge
+        def kind_findings(edge, aligned)
+          if edge[:kind] == "acl" && aligned.any? { |relationship| relationship.kind == :conformist }
+            return allowed?(aligned, :conformist_translates) ? [] : [conformist_translates_finding(edge)]
+          end
+
+          match = aligned.find { |relationship| IMPLEMENTS.fetch(edge[:kind], []).include?(relationship.kind) }
+          return mismatch_findings(edge, aligned) unless match
+
+          unpublished_findings(edge, match)
+        end
+
+        # A subscription names the supplier event it depends on, so it can be held to the
+        # relationship's published list. Other edges name a policy, which has no event to check.
+        def unpublished_findings(edge, relationship)
+          return [] unless edge[:kind] == "subscription" && relationship.published.to_a.any?
+          return [] if published?(relationship, edge[:via]) || relationship.acknowledges?(:unpublished_dependency)
+
+          [Finding.new(kind: :unpublished_dependency, severity: :error, subject: edge_subject(edge),
+                       message: "#{edge[:from]} reacts to #{edge[:via]}, which #{relationship.upstream} " \
+                                "does not publish to it (published: #{relationship.published.join(", ")})")]
+        end
+
+        # @return [Array<Finding>] the mismatch, unless an aligned relationship allows it
+        def mismatch_findings(edge, aligned)
+          allowed?(aligned, :relationship_kind_mismatch) ? [] : [kind_mismatch_finding(edge, aligned)]
+        end
+
+        # @return [Boolean] whether any of the relationships acknowledges the finding kind
+        def allowed?(relationships, finding) = relationships.any? { |relationship| relationship.acknowledges?(finding) }
+
+        # @return [Boolean] whether the event is in the relationship's published list, by name
+        def published?(relationship, event)
+          relationship.published.map { |name| event_tail(name) }.include?(event_tail(event))
+        end
+
+        # @return [String] the event's own name, without its context or aggregate qualifier
+        def event_tail(name)
+          parts = name.to_s.split(QUALIFIER)
+          parts.last.to_s
+        end
+
+        # @return [Boolean] whether the relationship has the supplier upstream and the consumer
+        #   downstream, or is a kind with no direction
+        def runs_from?(relationship, supplier, consumer)
+          MUTUAL.include?(relationship.kind) ||
+            (relationship.upstream == supplier && relationship.downstream == consumer)
+        end
+
+        # @return [Array<Finding>] one warning per declared relationship the wiring never uses
+        def unused_relationship_findings(map, edges)
+          map.relationships.filter_map do |relationship|
+            next if edges.any? { |edge| edge_uses?(edge, relationship) }
+            next if relationship.acknowledges?(:unused_relationship)
+
+            Finding.new(kind: :unused_relationship, severity: :warning,
+                        subject: "#{relationship.downstream} <- #{relationship.upstream}",
+                        message: "the map declares #{relationship.kind} here, but no wiring couples " \
+                                 "these contexts")
+          end
+        end
+
+        # @return [Boolean] whether the derived edge runs between the relationship's contexts
+        def edge_uses?(edge, relationship)
+          return edge_between?(edge, relationship) if MUTUAL.include?(relationship.kind)
+
+          edge[:from] == relationship.downstream && edge[:to] == relationship.upstream
+        end
+
+        def edge_between?(edge, relationship) = [edge[:from], edge[:to]].sort == relationship.pair
+
+        def edge_subject(edge) = "#{edge[:from]} -> #{edge[:to]}"
+
+        def reversed_note(declared)
+          first = declared.first
+          "the map declares #{first.upstream} as upstream of #{first.downstream}, the other way round"
+        end
+
+        def undeclared_finding(edge, why)
+          Finding.new(kind: :undeclared_coupling, severity: :error, subject: edge_subject(edge),
+                      message: "#{edge[:kind]} couples these contexts (#{edge[:via] || "attach"}), " \
+                               "and #{why}")
+        end
+
+        def kind_mismatch_finding(edge, aligned)
+          Finding.new(kind: :relationship_kind_mismatch, severity: :error, subject: edge_subject(edge),
+                      message: "the wiring is a #{edge[:kind]}, but the map declares " \
+                               "#{aligned.map(&:kind).join(", ")}")
+        end
+
+        def separate_ways_finding(edge)
+          Finding.new(kind: :separate_ways_violated, severity: :error, subject: edge_subject(edge),
+                      message: "the map declares these contexts separate ways, but #{edge[:kind]} couples them")
+        end
+
+        def conformist_translates_finding(edge)
+          Finding.new(kind: :conformist_translates, severity: :warning, subject: edge_subject(edge),
+                      message: "the map declares #{edge[:from]} a conformist of #{edge[:to]}, " \
+                               "yet it translates (#{edge[:via]}) — declare anticorruption_layer if so")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/lifecycle_checks.rb

@@ -17,10 +17,16 @@ module Hecks
             *unknown_transition_commands(lifecycle, Array(declaring.commands).map(&:hecks_name), subject),
             *unreachable_state_findings(lifecycle, full_states(lifecycle), reached, subject),
             *dead_transition_findings(lifecycle, reached, subject),
-            *stuck_state_findings(lifecycle, reached, subject)
+            *end_state_findings(lifecycle, reached, subject)
           ]
         end
 
+        # The findings about where the lifecycle ends: states nothing leaves, and `:terminal` marks
+        # a transition contradicts.
+        def end_state_findings(lifecycle, reached, subject)
+          [*stuck_state_findings(lifecycle, reached, subject), *terminal_exit_findings(lifecycle, subject)]
+        end
+
         # @return [String] the aggregate's name, or `Aggregate::Entity` for one of its entities
         def lifecycle_subject(aggregate, declaring)
           return aggregate.hecks_name if declaring.equal?(aggregate)
@@ -50,19 +56,35 @@ module Hecks
         end
 
         # Finds every reached state with no transition ever leaving it, unless any
-        # transition in this lifecycle is unconstrained.
+        # transition in this lifecycle is unconstrained or the state is marked `:terminal`.
         def stuck_state_findings(lifecycle, reached, subject)
           any_unconstrained = lifecycle.transitions.any? { |_, t| !t.constrained? }
-          (reached - terminal_exempt(lifecycle)).filter_map do |state|
+          (reached - terminal_exempt(lifecycle) - terminal_states(lifecycle)).filter_map do |state|
             next if any_unconstrained
-            next if lifecycle.transitions.any? { |_, t| t.constrained? && Array(t.from).include?(state) }
+            next if leaves?(lifecycle, state)
 
             Finding.new(kind: :stuck_state, severity: :warning, subject: subject,
                         message: "#{state.inspect} is reached but no transition ever leaves it — " \
-                                 "fine if that is meant to be terminal")
+                                 "add a transition out, or `mark :terminal, #{state.inspect}` if it is meant to end")
+          end
+        end
+
+        # Finds every state marked `:terminal` that a constrained transition still leaves.
+        def terminal_exit_findings(lifecycle, subject)
+          terminal_states(lifecycle).select { |state| leaves?(lifecycle, state) }.map do |state|
+            Finding.new(kind: :terminal_has_exit, severity: :error, subject: subject,
+                        message: "#{state.inspect} is marked :terminal but a transition leaves it")
           end
         end
 
+        # @return [Array<String>] the states the lifecycle marks `:terminal`
+        def terminal_states(lifecycle) = lifecycle.marked(:terminal) || []
+
+        # @return [Boolean] whether a constrained transition names `state` in its `from:`
+        def leaves?(lifecycle, state)
+          lifecycle.transitions.any? { |_, t| t.constrained? && Array(t.from).include?(state) }
+        end
+
         # Finds every transition named after a command the construct doesn't declare.
         def unknown_transition_commands(lifecycle, commands, subject)
           lifecycle.transitions.filter_map do |command, _transition|

data/lib/hecks/bluebook/model_check/one_of_checks.rb

@@ -0,0 +1,106 @@
+require_relative "../one_of_union"
+require_relative "../expression/ast_json"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The check over a tagged reference (`reference_to one_of(A, B), as: :subject`, ADR 0127):
+      # once anything branches on the subject's type, every variant of the union must be handled.
+      # A branch is a command `given`/`ensures` of the owning aggregate comparing `subject.type`
+      # with a name, or a read model `where` on the owning aggregate's `subject.type`.
+      module OneOfChecks
+        # Flags each tagged reference whose branches leave a variant unhandled, or name a type
+        # the union does not hold.
+        #
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
+        # @return [Array<Finding>] one :one_of_branch_unhandled error per such reference
+        def one_of_branch_findings(bluebook)
+          bluebook.aggregates.flat_map do |aggregate|
+            OneOfUnion.attributes(aggregate).filter_map { |attribute| one_of_branch_finding(bluebook, aggregate, attribute) }
+          end
+        end
+
+        # @return [Finding, nil] the finding for one tagged reference, or nil when no branch
+        #   names its type or every branch set covers the union exactly
+        def one_of_branch_finding(bluebook, aggregate, attribute)
+          tested = branched_types(bluebook, aggregate, attribute.name.to_s)
+          return nil if tested.empty?
+
+          variants = OneOfUnion.variants(aggregate, attribute)
+          missing = variants - tested
+          stray = tested - variants
+          return nil if missing.empty? && stray.empty?
+
+          Finding.new(kind: :one_of_branch_unhandled, severity: :error,
+                      subject: "#{aggregate.hecks_name}.#{attribute.name}",
+                      message: one_of_branch_message(attribute.name, missing, stray))
+        end
+
+        def one_of_branch_message(name, missing, stray)
+          parts = []
+          parts << "no branch handles #{missing.join(", ")}" unless missing.empty?
+          parts << "a branch names #{stray.join(", ")}, which the union does not hold" unless stray.empty?
+          "branches on #{name}.type, but #{parts.join("; ")} — handle every variant of the union"
+        end
+
+        # Every type name a branch of `aggregate` compares `<name>.type` with, each once.
+        def branched_types(bluebook, aggregate, name)
+          (rule_branch_types(aggregate, name) + where_branch_types(bluebook, aggregate, name)).uniq
+        end
+
+        # The names the owning aggregate's command rules compare `<name>.type` with.
+        def rule_branch_types(aggregate, name)
+          rules = aggregate.commands.flat_map { |command| Array(command.givens) + Array(command.ensures) }
+          rules.flat_map { |rule| compared_types(rule_ast(rule), name) }
+        end
+
+        # A registry bluebook is a round-trip product that keeps a rule's canonical text, not its
+        # tree, so the tree is read again from the text.
+        def rule_ast(rule)
+          return rule.ast if rule.ast
+          return nil if rule.canonical.to_s.empty?
+
+          Expression::AstJson.emit_predicate(rule.canonical)
+        end
+
+        # The names a read model over the owning aggregate filters `<name>.type` by.
+        def where_branch_types(bluebook, aggregate, name)
+          clauses = read_models_over(bluebook, aggregate).flat_map(&:wheres)
+          clauses.select { |clause| clause.field.to_s == "#{name}.type" }.map { |clause| clause.value.to_s }
+        end
+
+        # The read models that gather `aggregate` as one of their heads.
+        def read_models_over(bluebook, aggregate)
+          owner = aggregate.hecks_name.to_s
+          bluebook.read_models.select { |model| model.aggregate_heads.any? { |head| head[:aggregate].to_s == owner } }
+        end
+
+        # Walks an expression tree for comparisons of the lookup `<name>.type` with a string.
+        def compared_types(node, name)
+          return node.flat_map { |child| compared_types(child, name) } if node.is_a?(Array)
+          return [] unless node.is_a?(Hash)
+
+          found = type_comparison(node, name)
+          found + node.values.flat_map { |child| compared_types(child, name) }
+        end
+
+        def type_comparison(node, name)
+          return [] unless field(node, :op) == "compare"
+
+          sides = [field(node, :left), field(node, :right)]
+          literal = sides.find { |side| field(side, :op) == "str" }
+          sides.any? { |side| type_lookup?(side, name) } && literal ? [field(literal, :value).to_s] : []
+        end
+
+        def type_lookup?(side, name) = field(side, :op) == "lookup" && Array(field(side, :path)).map(&:to_s) == [name, "type"]
+
+        # A key of an expression node, whether it was read with String or Symbol keys.
+        def field(node, key)
+          return nil unless node.is_a?(Hash)
+
+          node.key?(key) ? node[key] : node[key.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/orphan_checks.rb

@@ -0,0 +1,129 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The check that stands in for `dependent: :destroy`: an aggregate holding `reference_to`
+      # another must say, with a policy, what becomes of its rows when that other one's life ends.
+      #
+      # A record's life ends at an ending state: one its lifecycle reaches, that is not the
+      # default, and that no transition leaves. The language has no delete verb, so an ending
+      # state is the only way a record ends. A holder that cannot end itself is a record that
+      # outlives what it points at by design, a statement or a ledger line, and is not checked.
+      # (ADR 0121)
+      module OrphanChecks
+        # The separator between an aggregate and what it owns in `Aggregate.Name` or
+        # `Aggregate::Name`.
+        OWNER_SEPARATOR = /::|\./
+        # One way an aggregate's life ends: the state, the command that reaches it, and the
+        # events that command emits, any of which a policy may hear.
+        Ending = Struct.new(:state, :command, :events, keyword_init: true)
+
+        # Flags each pair of a holder that can end and an aggregate it references, for each of
+        # the referenced aggregate's endings no policy acts on the holder's rows for.
+        #
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook to check
+        # @return [Array<Finding>] one :orphaned_reference warning per unhandled ending
+        def orphan_findings(bluebook)
+          endings = bluebook.aggregates.to_h { |aggregate| [aggregate.hecks_name, life_endings(aggregate)] }
+          bluebook.aggregates.flat_map do |holder|
+            endings[holder.hecks_name].empty? ? [] : holder_orphan_findings(bluebook, holder, endings)
+          end
+        end
+
+        # @param endings [Hash{String => Array<Ending>}] each aggregate's name, to its endings
+        # @return [Array<Finding>] the holder's findings, one per unhandled ending of each
+        #   aggregate it references
+        def holder_orphan_findings(bluebook, holder, endings)
+          referenced_attributes(holder).slice(*endings.keys).flat_map do |target, attributes|
+            next [] if Acknowledgements.held?(holder, :orphaned_reference, subject: target)
+
+            unhandled_endings(bluebook, holder, endings[target], target).map do |ending|
+              orphan_finding(holder, target, attributes, ending)
+            end
+          end
+        end
+
+        # @return [Array<Ending>] every transition of the aggregate's own lifecycle that ends it
+        def life_endings(aggregate)
+          lifecycle = aggregate.lifecycle
+          return [] unless lifecycle
+
+          ending = ending_states(lifecycle)
+          lifecycle.transitions.filter_map do |command, transition|
+            next unless ending.include?(transition.target)
+
+            Ending.new(state: transition.target, command: command, events: emitted_by(aggregate, command))
+          end
+        end
+
+        # A lifecycle with an unconstrained transition can leave any state, so it has none.
+        #
+        # @return [Array<String>] the reached states, other than the default, nothing leaves
+        def ending_states(lifecycle)
+          transitions = lifecycle.transitions.map(&:last)
+          return [] unless transitions.all?(&:constrained?)
+
+          left = transitions.flat_map { |transition| Array(transition.from) }
+          reachable_states(lifecycle).to_a - [lifecycle.default] - left
+        end
+
+        # @return [Hash{String => Array<String>}] each aggregate the holder or one of its entities
+        #   references, to the names of the attributes that hold the reference
+        def referenced_attributes(holder)
+          reference_attributes(holder).group_by(&:target_name)
+                                      .transform_values { |attributes| attributes.map { |attribute| attribute.name.to_s } }
+        end
+
+        # @return [Array<Bluebook::Attribute>] every reference the holder or its entities hold
+        def reference_attributes(holder)
+          [holder, *holder.entities].flat_map(&:attributes).select(&:reference?)
+        end
+
+        # @return [Array<Ending>] the target's endings with no policy acting on the holder
+        def unhandled_endings(bluebook, holder, endings, target)
+          endings.reject do |ending|
+            bluebook.policies.any? { |policy| handles?(policy, holder, target, ending) }
+          end
+        end
+
+        # A policy handles an ending when it hears one of the ending's events and fans out over,
+        # or triggers a command of, the holder.
+        def handles?(policy, holder, target, ending)
+          return false unless ending.events.include?(event_name(policy.on_event, target))
+
+          [policy.for_each, policy.trigger_command].compact.any? do |named|
+            owner_name(named) == holder.hecks_name
+          end
+        end
+
+        # @return [String, nil] the event a policy hears, when it is one of `target`'s events
+        def event_name(on_event, target)
+          owner, event = on_event.to_s.split(OWNER_SEPARATOR, 2)
+          event ? (event if owner == target) : owner
+        end
+
+        # @return [String] the aggregate a dotted `Aggregate.Name` reference names
+        def owner_name(named) = named.to_s.split(OWNER_SEPARATOR).first
+
+        # @return [Array<String>] the event names the aggregate's command emits
+        def emitted_by(aggregate, command)
+          Array(aggregate.commands.find { |declared| declared.hecks_name == command }&.emits).map(&:to_s)
+        end
+
+        def orphan_finding(holder, target, attributes, ending)
+          Finding.new(kind: :orphaned_reference, severity: :warning,
+                      subject: "#{holder.hecks_name} -> #{target}",
+                      message: "#{holder.hecks_name} holds reference_to #{target} (#{attributes.join(", ")}) " \
+                               "and #{target} ends at #{ending.state.inspect} by #{ending.command}, " \
+                               "but #{orphan_remedy(holder, ending)}")
+        end
+
+        def orphan_remedy(holder, ending)
+          return "#{ending.command} emits no event, so no policy can act on #{holder.hecks_name}'s rows" if ending.events.empty?
+
+          "no policy on #{ending.events.join(" or ")} acts on #{holder.hecks_name}'s rows; " \
+            "add one that fans out over them (for_each \"#{holder.hecks_name}.<query>\") and ends each"
+        end
+      end
+    end
+  end
+end