hecks 3.5.0 → 3.6.0

data/lib/hecks/bluebook/meta_validator.rb

@@ -1,12 +1,15 @@
 require "digest"
 require "json"
 require_relative "meta_validator/verdict_cache"
+require_relative "meta_validator/modes"
 
 module Hecks
   module Bluebook
     # Judges a bluebook by dispatching it into the language declared in itself.
     # Refusals become `DSL::Malformed`; the meta-domain does the judging, not a builder.
     module MetaValidator
+      extend Modes
+
       # Deterministic file order becomes the source order exported to IR.
       GRAMMAR_DIR   = File.expand_path("../language/bluebook", __dir__).freeze
       GRAMMAR_FILES = Dir.glob(File.join(GRAMMAR_DIR, "*.bluebook")).freeze
@@ -27,127 +30,6 @@ module Hecks
       # and replaced by their own self-assembled graphs.
       LANGUAGE_CHAPTERS = %w[Bluebook World Hecksagon].freeze
 
-      # Whether the language's own grammar is still loading raw, unjudged.
-      # Judging it while it loads would recurse, so the bootstrap sets this
-      # and the fixpoint clears it once every grammar file is merged.
-      #
-      # @return [Boolean]
-      def self.bootstrapping? = @bootstrapping
-
-      # Whether `call` is queuing chapters instead of judging them, while a
-      # chapter's own files are still being merged (see `defer`).
-      #
-      # @return [Boolean]
-      def self.deferring? = @deferring
-
-      # Queues every chapter `call` sees while the block runs, instead of
-      # judging them immediately (see `deferred_chapters`).
-      #
-      # @yield the caller's own load of every file in one chapter window
-      # @return [Object] the block's own return value
-      def self.defer
-        previous   = @deferring
-        @deferring = true
-        yield
-      ensure
-        @deferring = previous
-      end
-
-      # The chapters queued while `defer`'s block ran, awaiting
-      # `judge_deferred!`.
-      #
-      # @return [Array<String>] each deferred chapter's own `hecks_name`,
-      #   queued during the current or most recent `defer` window
-      def self.deferred_chapters = @deferred_chapters ||= []
-
-      # Judges every chapter 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
-      #   (`BluebookBuilder.validate_assembled!`) or the meta-domain itself
-      #   (`call`) refuses it
-      def self.judge_deferred!(registry)
-        pending = deferred_chapters.uniq
-        @deferred_chapters = []
-        return unless registry
-
-        pending.each do |name|
-          chapter = registry.bluebook(name)
-          next unless chapter
-
-          # Bare chapter-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.
-          builder = registry.bluebook_builder(name) { raise "internal: no open builder for #{name}" }
-          builder.resolve_pending_chapter_givens!
-          # Same, one level down: entity-scoped pending givens.
-          builder.resolve_pending_chapter_entity_givens!
-
-          # Whole-chapter checks (hops, projected fields, event shapes) were
-          # skipped per file while deferring; `chapter` 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))
-        end
-      end
-
-      # Whether meta-domain judging is off (ignored while a fixpoint build
-      # is forced).
-      # Stack-restored, not a bare flag, so a disabled window can never
-      # leak past its own scope.
-      #
-      # @return [Boolean]
-      def self.disabled? = @disabled && !@forcing_fixpoint
-
-      # Runs `block` with `disabled?` true, restoring it afterward — for a
-      # growth spec that boots a scratch bluebook without validation overhead.
-      #
-      # @yield the caller's own boot, with `disabled?` true throughout
-      # @return [Object] the block's own return value
-      def self.while_disabled
-        previous  = @disabled
-        @disabled = true
-        yield
-      ensure
-        @disabled = previous
-      end
-
-      # (ADR 0025) Whether frozen era text is currently being shadow-parsed
-      # by `EraGuard`. Judging it again here would refuse history whenever a
-      # spelling it used gets removed from the live grammar.
-      #
-      # @return [Boolean]
-      def self.shadow_parsing? = @shadow_parsing
-
-      # Wraps `block` with `shadow_parsing?` true, restoring it afterward.
-      #
-      # @yield the caller's own shadow-parse of one piece of frozen era text
-      # @return [Object] the block's own return value
-      def self.while_shadow_parsing
-        previous        = @shadow_parsing
-        @shadow_parsing = true
-        yield
-      ensure
-        @shadow_parsing = previous
-      end
-
-      # Wraps `block` with `disabled?` forced false, restoring it afterward.
-      # Only `grammar_registry`'s one-time fixpoint build uses this.
-      #
-      # @yield the one-time fixpoint build, with `disabled?` forced false
-      #   throughout
-      # @return [Object] the block's own return value
-      def self.while_forcing_fixpoint
-        previous          = @forcing_fixpoint
-        @forcing_fixpoint = true
-        yield
-      ensure
-        @forcing_fixpoint = previous
-      end
-
       # Process-wide judging cache, keyed on a SHA-256 digest of the judged
       # artifact so a changed bluebook is always re-judged.
       #
@@ -166,14 +48,9 @@ module Hecks
       #   while disabled/bootstrapping/shadow-parsing
       # @raise [DSL::Malformed] if `WorldJudge` finds `world` malformed
       def self.call_world(world)
-        return world if disabled? || bootstrapping? || shadow_parsing?
-
-        key = Digest::SHA256.hexdigest(JSON.generate([world.domain, world.realm, world.latest, world.settings]))
-        refusals = verdicts[key] ||= WorldJudge.new(world).refusals
-        return world if refusals.empty?
-
-        raise DSL::Malformed,
-              "#{world.domain}'s world is not well formed; #{refusals.join('; ')}"
+        judge_door(world, WorldJudge, "#{world.domain}'s world") do
+          JSON.generate([world.domain, world.realm, world.latest, world.settings])
+        end
       end
 
       # Judges `port` through the meta-domain's own `PortJudge` door.
@@ -183,14 +60,7 @@ module Hecks
       #   disabled/bootstrapping/shadow-parsing
       # @raise [DSL::Malformed] if `PortJudge` finds `port` malformed
       def self.call_port(port)
-        return port if disabled? || bootstrapping? || shadow_parsing?
-
-        key = Digest::SHA256.hexdigest(JSON.generate([port.name, port.verb, port.signal]))
-        refusals = verdicts[key] ||= PortJudge.new(port).refusals
-        return port if refusals.empty?
-
-        raise DSL::Malformed,
-              "#{port.name}'s port is not well formed; #{refusals.join('; ')}"
+        judge_door(port, PortJudge, "#{port.name}'s port") { JSON.generate([port.name, port.verb, port.signal]) }
       end
 
       # Judges `adapter` through the meta-domain's own `AdapterJudge` door.
@@ -200,36 +70,44 @@ module Hecks
       #   while disabled/bootstrapping/shadow-parsing
       # @raise [DSL::Malformed] if `AdapterJudge` finds `adapter` malformed
       def self.call_adapter(adapter)
-        return adapter if disabled? || bootstrapping? || shadow_parsing?
-
-        key = Digest::SHA256.hexdigest(JSON.generate([adapter.name, adapter.port, adapter.fields, adapter.secrets]))
-        refusals = verdicts[key] ||= AdapterJudge.new(adapter).refusals
-        return adapter if refusals.empty?
-
-        raise DSL::Malformed,
-              "#{adapter.name}'s adapter is not well formed; #{refusals.join('; ')}"
+        judge_door(adapter, AdapterJudge, "#{adapter.name}'s adapter") do
+          JSON.generate([adapter.name, adapter.port, adapter.fields, adapter.secrets])
+        end
       end
 
       # Judges `translation` through the meta-domain's own `TranslationJudge`
       # door, walking every nested aggregate's own rule table in one pass.
       #
+      # `Translation` has no `.to_h`; `.inspect` embeds an object-id, so
+      # structurally-identical translations never cache-hit here (a lost
+      # optimization, not a correctness issue).
+      #
       # @param translation [Bluebook::Translation] the translation to judge
       # @return [Bluebook::Translation] `translation` unchanged, if well
       #   formed or while disabled/bootstrapping/shadow-parsing
       # @raise [DSL::Malformed] if `TranslationJudge` finds `translation`
       #   malformed
       def self.call_translation(translation)
-        return translation if disabled? || bootstrapping? || shadow_parsing?
-
-        # `Translation` has no `.to_h`; `.inspect` embeds an object-id, so
-        # structurally-identical translations never cache-hit here (a lost
-        # optimization, not a correctness issue).
-        key = Digest::SHA256.hexdigest(translation.inspect)
-        refusals = verdicts[key] ||= TranslationJudge.new(translation).refusals
-        return translation if refusals.empty?
+        judge_door(translation, TranslationJudge, "#{translation.domain}'s translation") { translation.inspect }
+      end
 
-        raise DSL::Malformed,
-              "#{translation.domain}'s translation is not well formed; #{refusals.join('; ')}"
+      # The one door every artifact but a chapter goes through: skip while judging is off,
+      # else judge once per distinct `key_text` and refuse a malformed artifact.
+      #
+      # @param subject [Object] the artifact to judge
+      # @param judge [Class] the judge to build over `subject`; it answers `refusals`
+      # @param label [String] how the refusal names `subject`
+      # @yieldreturn [String] the text whose SHA-256 digest keys the verdict
+      # @return [Object] `subject` unchanged, if well formed or while judging is off
+      # @raise [DSL::Malformed] if `judge` finds `subject` malformed
+      def self.judge_door(subject, judge, label)
+        return subject if disabled? || bootstrapping? || shadow_parsing?
+
+        key = Digest::SHA256.hexdigest(yield)
+        refusals = verdicts[key] ||= judge.new(subject).refusals
+        return subject if refusals.empty?
+
+        raise DSL::Malformed, "#{label} is not well formed; #{refusals.join("; ")}"
       end
 
       # Dispatches `bluebook` into the language and returns the graph the
@@ -247,22 +125,31 @@ module Hecks
       def self.call(bluebook)
         return bluebook if disabled? || bootstrapping? || shadow_parsing?
 
-        if deferring?
-          deferred_chapters << bluebook.hecks_name
-          return bluebook
-        end
-
-        key = Digest::SHA256.hexdigest(JSON.generate(bluebook.to_h))
-        held = verdicts[key] || (verdicts[key] = hold(bluebook).tap { |fresh| VerdictCache.record(key, fresh) })
+        return defer_chapter(bluebook) if deferring?
 
+        held = held_verdict(bluebook)
         unless held[:refusals].empty?
           raise DSL::Malformed,
-                "#{bluebook.hecks_name} is not a well-formed bluebook; #{held[:refusals].join('; ')}"
+                "#{bluebook.hecks_name} is not a well-formed bluebook; #{held[:refusals].join("; ")}"
         end
 
         Assembly.call(held[:declaration])
       end
 
+      # @param bluebook [Object] a built bluebook chapter graph
+      # @return [Object] `bluebook`, queued for `judge_deferred!`
+      def self.defer_chapter(bluebook)
+        deferred_chapters << bluebook.hecks_name
+        bluebook
+      end
+
+      # @param bluebook [Object] a built bluebook chapter graph
+      # @return [Hash{Symbol => Object}] the verdict `hold` produced for it, cached by digest
+      def self.held_verdict(bluebook)
+        key = Digest::SHA256.hexdigest(JSON.generate(bluebook.to_h))
+        verdicts[key] || (verdicts[key] = hold(bluebook).tap { |fresh| VerdictCache.record(key, fresh) })
+      end
+
       # Dispatches `bluebook` into the meta-domain and reads the result back.
       # A refused chapter carries only its refusals — the records are
       # half-written by definition.
@@ -341,23 +228,20 @@ module Hecks
       # @return [Runtime::Registry] `registry`, unchanged in identity
       def self.load_grammar_into(registry)
         @bootstrapping = true
-        Hecks.with_registry(registry) do
-          Kernel.load(File.expand_path("../ports/persistence.port", __dir__))
-          Kernel.load(File.expand_path("../ports/extraction.port", __dir__))
-          Kernel.load(File.expand_path("../adapters/driven/memory.adapter", __dir__))
-          Kernel.load(File.expand_path("../adapters/driven/prism.adapter", __dir__))
-          GRAMMAR_FILES.each { |file| Kernel.load(file) }
-          WORLD_GRAMMAR.each { |file| Kernel.load(file) }
-          HECKSAGON_GRAMMAR.each { |file| Kernel.load(file) }
-          Kernel.load(PORT_GRAMMAR)
-          Kernel.load(ADAPTER_GRAMMAR)
-          TRANSLATION_GRAMMAR.each { |file| Kernel.load(file) }
-        end
+        Hecks.with_registry(registry) { grammar_files.each { |file| Kernel.load(file) } }
         registry
       ensure
         @bootstrapping = false
       end
 
+      # @return [Array<String>] every file `load_grammar_into` loads, in load order
+      def self.grammar_files
+        preamble = ["../ports/persistence.port", "../ports/extraction.port",
+                    "../adapters/driven/memory.adapter", "../adapters/driven/prism.adapter"]
+        preamble.map { |path| File.expand_path(path, __dir__) } +
+          GRAMMAR_FILES + WORLD_GRAMMAR + HECKSAGON_GRAMMAR + [PORT_GRAMMAR, ADAPTER_GRAMMAR] + TRANSLATION_GRAMMAR
+      end
+
       # A dispatcher over the shared grammar registry with its records
       # cleared, so one bluebook's judging can never see another's records.
       #

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

@@ -0,0 +1,122 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks over a lifecycle read as a state machine: states nothing reaches, transitions
+      # that can never fire, states nothing leaves, and transitions naming no command.
+      module LifecycleChecks
+        # Runs every lifecycle-shaped check for one declaring construct — the aggregate
+        # itself, or one of its entities — if it declares a lifecycle at all.
+        def lifecycle_findings(aggregate, declaring)
+          lifecycle = declaring.lifecycle
+          return [] unless lifecycle
+
+          subject = lifecycle_subject(aggregate, declaring)
+          reached = reachable_states(lifecycle)
+
+          [
+            *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
+
+        # @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)
+
+          "#{aggregate.hecks_name}::#{declaring.hecks_name}"
+        end
+
+        # Finds every declared state the lifecycle's own reachability walk never reaches.
+        def unreachable_state_findings(lifecycle, full, reached, subject)
+          (full - reached.to_a).map do |state|
+            Finding.new(kind: :unreachable_state, severity: :error, subject: subject,
+                        message: "#{state.inspect} is declared (in a transition's from: or target) " \
+                                 "but no path from #{lifecycle.default.inspect} ever reaches it")
+          end
+        end
+
+        # Finds every constrained transition whose from: states are all unreached.
+        def dead_transition_findings(lifecycle, reached, subject)
+          lifecycle.transitions.filter_map do |command, transition|
+            next unless transition.constrained?
+            next if Array(transition.from).any? { |source| reached.include?(source) }
+
+            Finding.new(kind: :dead_transition, severity: :error, subject: subject,
+                        message: "#{command} from #{Array(transition.from).inspect} can never fire — " \
+                                 "none of those states is ever reached")
+          end
+        end
+
+        # Finds every reached state with no transition ever leaving it, unless any
+        # transition in this lifecycle is unconstrained.
+        def stuck_state_findings(lifecycle, reached, subject)
+          any_unconstrained = lifecycle.transitions.any? { |_, t| !t.constrained? }
+          (reached - terminal_exempt(lifecycle)).filter_map do |state|
+            next if any_unconstrained
+            next if lifecycle.transitions.any? { |_, t| t.constrained? && Array(t.from).include?(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")
+          end
+        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|
+            next if commands.include?(command)
+
+            Finding.new(kind: :unknown_command, severity: :error, subject: subject,
+                        message: "a transition names #{command.inspect}, which this construct declares no command for")
+          end
+        end
+
+        # Every state `lifecycle` declares in any role — default, target, or from,
+        # unique.
+        #
+        # @param lifecycle [Bluebook::Lifecycle] the lifecycle being checked
+        # @return [Array<String>] every state lifecycle declares, unique
+        def full_states(lifecycle)
+          (
+            [lifecycle.default] +
+            lifecycle.transitions.map { |_, t| t.target } +
+            lifecycle.transitions.flat_map { |_, t| Array(t.from) }
+          ).uniq
+        end
+
+        # Least fixpoint from the default state: an unconstrained transition always
+        # fires; a constrained one fires once any of its named sources is reached.
+        def reachable_states(lifecycle)
+          reached = Set.new([lifecycle.default])
+          # `transitions` is an Array of [from, transition] pairs, not a Hash.
+          transitions = lifecycle.transitions.map { |_, transition| transition }
+          loop { break unless transitions.map { |transition| reach(transition, reached) }.any? }
+          reached
+        end
+
+        # Adds `transition`'s target to `reached` when the transition can fire from what is
+        # already reached.
+        #
+        # @return [Set, nil] truthy when the target was newly reached
+        def reach(transition, reached)
+          return if transition.constrained? && Array(transition.from).none? { |source| reached.include?(source) }
+
+          reached.add?(transition.target)
+        end
+
+        # Exempts only the lifecycle's own default state, and only when the lifecycle
+        # declares real transitions elsewhere: entering default implies nothing about
+        # ever leaving it, unlike a state some transition explicitly delivered to. An
+        # empty lifecycle still warns — that reads as unfinished wiring, not a deliberate rest.
+        def terminal_exempt(lifecycle)
+          return [] if lifecycle.transitions.empty?
+
+          outgoing_sources = lifecycle.transitions.flat_map { |_, t| Array(t.from) }.to_set
+          outgoing_sources.include?(lifecycle.default) ? [] : [lifecycle.default]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks over a policy: reactions to events nothing emits, triggers that name no
+      # command, and the relationship a cross-domain reaction claims against its hecksagon.
+      module PolicyChecks
+        # Runs every same-domain policy check, or defers to
+        # cross_domain_policy_findings for a cross-domain policy.
+        def policy_findings(bluebook, policy, hecksagon, known_domains, global_emitted_events = nil)
+          return cross_domain_policy_findings(policy, hecksagon, known_domains) if policy.target_domain
+
+          [
+            deaf_policy_finding(policy, emitted_events(bluebook), global_emitted_events),
+            unknown_trigger_finding(bluebook, policy)
+          ].compact
+        end
+
+        # `policy.event_name`, not `bare` — an aggregate-scoped on_event carries a
+        # "." qualifier bare doesn't strip. `global_emitted_events` is a fallback for
+        # a translates reaction, whose whole point is reacting to a foreign event.
+        def deaf_policy_finding(policy, emitted, global_emitted_events)
+          return if emitted.include?(policy.event_name) || global_emitted_events&.include?(policy.event_name)
+
+          Finding.new(kind: :deaf_policy, severity: :error, subject: policy.name,
+                      message: "on #{policy.on_event.inspect}, which no command in this domain emits")
+        end
+
+        # Completed to the same FQN verbs_of builds, then compared as a parsed
+        # triple — not a string — so a port-operation trigger's spelling matches
+        # the same way an entity command's does (see handler_findings).
+        def unknown_trigger_finding(bluebook, policy)
+          qualified = Naming.split_verb("#{bluebook.name}::#{policy.trigger_command}")
+          return if qualified && triggerable_verbs(bluebook).include?(qualified)
+
+          Finding.new(kind: :unknown_trigger, severity: :error, subject: policy.name,
+                      message: "trigger #{policy.trigger_command.inspect} resolves to no command " \
+                               "this domain declares")
+        end
+
+        # `attaches` is a Shared Kernel relationship (X merges in, no boundary);
+        # `across` is Customer/Supplier (real cross-Lambda RPC). This checks the choice
+        # between them instead of leaving it as an unenforced comment. (ADR 0025)
+        def cross_domain_policy_findings(policy, hecksagon, known_domains)
+          return expected_undelivered_findings(policy, hecksagon, known_domains) if policy.expect_undelivered
+          # No sibling hecksagon loaded — nothing to check a relationship against.
+          return [] unless hecksagon
+
+          [relationship_finding(policy, hecksagon), unknown_target_finding(policy, known_domains)].compact
+        end
+
+        # @return [Finding, nil] the finding for an `across` target that is both attached and
+        #   dispatched to, or for one the hecksagon never acknowledges; `nil` when neither
+        def relationship_finding(policy, hecksagon)
+          target = policy.target_domain
+          return contradictory_relationship_finding(policy, target) if hecksagon.attaches?(target)
+          return unless hecksagon.subscriptions.none? { |subscribed| Naming.qualifier(subscribed) == target }
+
+          # Checked here at model-check time; subscribe itself is never routed at
+          # runtime (see hecksagon.md's own "checked, not routed" section).
+          Finding.new(kind: :unacknowledged_relationship, severity: :error, subject: policy.name,
+                      message: "across #{target.inspect} declares a Customer/Supplier " \
+                               "relationship, but nothing in this hecksagon records the " \
+                               "expectation — add subscribe \"#{target}.SomeEvent\" for what " \
+                               "you expect back from it, or attaches #{target.inspect} to " \
+                               "attach it in-process instead")
+        end
+
+        # Shared Kernel and Customer/Supplier are mutually exclusive claims about
+        # the same target — declaring both means either a pointless RPC to a
+        # domain already local, or an attaches that isn't doing its job.
+        def contradictory_relationship_finding(policy, target)
+          Finding.new(kind: :contradictory_relationship, severity: :error, subject: policy.name,
+                      message: "across #{target.inspect} dispatches over RPC (Customer/Supplier), " \
+                               "but this hecksagon also attaches #{target.inspect} (Shared " \
+                               "Kernel) — #{target} is already loaded in-process here, so the two " \
+                               "relationship declarations contradict each other for the same " \
+                               "target domain")
+        end
+
+        # A heuristic, not proof: an external hecks consumer's own domain lives in a
+        # repo this corpus scan can't see, so "unknown here" isn't necessarily a typo.
+        # A domain undefined on purpose declares so via expect_undelivered instead.
+        def unknown_target_finding(policy, known_domains)
+          target = policy.target_domain
+          return unless known_domains && !known_domains.include?(target)
+
+          Finding.new(kind: :unknown_target_domain, severity: :error, subject: policy.name,
+                      message: "across #{target.inspect} names a domain nowhere in the corpus " \
+                               "this check has booted — a typo, or a target intentionally never " \
+                               "reached, which the policy itself declares with " \
+                               "across #{target.inspect}, expect_undelivered: true")
+        end
+
+        # Holds an expect_undelivered declaration to its word: the two findings an
+        # unreachable target would otherwise raise are suppressed (that's the point of
+        # the declaration), but if the target turns out reachable after all, the stale
+        # declaration itself is now the error.
+        def expected_undelivered_findings(policy, hecksagon, known_domains)
+          target  = policy.target_domain
+          reached = delivery_routes(target, hecksagon, known_domains)
+          return [] if reached.empty?
+
+          [Finding.new(kind: :stale_undelivered_expectation, severity: :error, subject: policy.name,
+                       message: "across #{target.inspect}, expect_undelivered: true — but #{reached.join(" and ")}, " \
+                                "so the reaction can be delivered after all; drop expect_undelivered: or remove " \
+                                "what reaches #{target}")]
+        end
+
+        # @return [Array<String>] each way `target` turns out reachable, in the order they are told
+        def delivery_routes(target, hecksagon, known_domains)
+          routes = []
+          routes << "#{target} is a domain this corpus boots" if known_domains&.include?(target)
+          routes.concat(hecksagon_routes(target, hecksagon)) if hecksagon
+          routes
+        end
+
+        # @return [Array<String>] how the hecksagon reaches `target`: it attaches or subscribes
+        def hecksagon_routes(target, hecksagon)
+          routes = []
+          routes << "this hecksagon attaches #{target.inspect}" if hecksagon.attaches?(target)
+          if hecksagon.subscriptions.any? { |subscribed| Naming.qualifier(subscribed) == target }
+            routes << "this hecksagon subscribes to #{target}"
+          end
+          routes
+        end
+      end
+    end
+  end
+end