hecks 0.2.0 → 0.3.0

data/lib/hecks/bluebook/model_check.rb

@@ -0,0 +1,318 @@
+require "set"
+
+module Hecks
+  module Bluebook
+    # Lightweight formal methods over the IR — the same family as TLA+/
+    # Alloy/P: every lifecycle is a declared finite state machine and
+    # every process manager a declared protocol, and BOTH are already
+    # data, not code, so they can be MODEL-CHECKED rather than merely
+    # executed. Static analysis only — no bluebook boots twice, no
+    # runtime is touched — over what meta_validator/judge.rb and the
+    # builders' own `validate!` methods leave uncovered (an undeclared
+    # transition target, a dispatch to nowhere, a compensation nothing
+    # can ever reach).
+    #
+    # THE RARE PROPERTY THIS RESTS ON: the model IS the implementation.
+    # A checker over TLA+ verifies a SPEC a human keeps in sync with
+    # code by hand ; this verifies the same IR the runtime dispatches
+    # against, so there is no second copy to drift.
+    module ModelCheck
+      Finding = Struct.new(:kind, :severity, :subject, :message, keyword_init: true) do
+        def to_s = "#{severity.to_s.upcase.ljust(7)} #{kind.to_s.ljust(20)} #{subject}  —  #{message}"
+      end
+
+      # A FINDING SHIPPED, NOT SILENCED — the coverage-gate idiom, empty
+      # allowlists enforced BOTH directions (spec/model_check_spec.rb holds
+      # this exact table: an error the checker reports and this does not
+      # name is a regression, an entry the checker no longer reports is
+      # stale and must be deleted). bin/model_check reads this same
+      # constant, so the tool and the spec can never drift apart.
+      #
+      # "banking"/ExternalSettlement — found on the first real run:
+      # ExternalSettlement declares `ends_on "ExternalTransferSent"`, and
+      # ExternalTransfer.Send genuinely emits it — the event is real, and
+      # the AGGREGATE reaches "sent" (its own, separate lifecycle) — but
+      # the SAGA'S protocol has no `on "ExternalTransferSent"` handler, so
+      # its own `state "sent"` is unreachable through the chain the
+      # checker walks, and the saga's own bookkeeping (saga_log, ends_on)
+      # never closes it. Real domain activity is unaffected; the saga's
+      # OWN tracking of it is not. Left named rather than redesigning a
+      # corpus fixture that is not this checker's to redesign.
+      # S7, ADR 0025 — the ExternalSettlement finding this used to
+      # allowlist is GONE, not just quieted: its "sent" state was a
+      # `state "x"` line never named by any handler's own from:/to:, a
+      # pure declaration-drift artifact. States are DERIVED from the
+      # transitions that name them now (ProcessManagerBuilder#derived_
+      # states), so a state nothing ever transitions into or out of no
+      # longer exists to be unreachable — the finding this allowlisted
+      # cannot occur any more, by construction.
+      ALLOWED_FINDINGS = {}.freeze
+
+      module_function
+
+      def call(bluebook)
+        findings = []
+        bluebook.aggregates.each do |aggregate|
+          findings.concat(lifecycle_findings(aggregate, aggregate))
+          aggregate.entities.each { |entity| findings.concat(lifecycle_findings(aggregate, entity)) }
+        end
+        bluebook.process_managers.each { |pm| findings.concat(saga_findings(bluebook, pm)) }
+        bluebook.policies.each { |policy| findings.concat(policy_findings(bluebook, policy)) }
+        findings
+      end
+
+      # ── lifecycles (aggregate AND entity — a piece may declare one too) ──
+
+      def lifecycle_findings(aggregate, declaring)
+        lifecycle = declaring.lifecycle
+        return [] unless lifecycle
+
+        subject = declaring.equal?(aggregate) ? aggregate.hecks_name : "#{aggregate.hecks_name}::#{declaring.hecks_name}"
+        commands = Array(declaring.commands).map(&:hecks_name)
+
+        findings = []
+        findings.concat(unknown_transition_commands(lifecycle, commands, subject))
+
+        full = full_states(lifecycle)
+        reached = reachable_states(lifecycle)
+
+        (full - reached.to_a).each do |state|
+          findings << 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
+
+        lifecycle.transitions.each do |command, transition|
+          next unless transition.constrained?
+          next if Array(transition.from).any? { |source| reached.include?(source) }
+
+          findings << 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
+
+        any_unconstrained = lifecycle.transitions.any? { |_, t| !t.constrained? }
+        (reached - terminal_exempt(lifecycle)).each do |state|
+          next if any_unconstrained
+          next if lifecycle.transitions.any? { |_, t| t.constrained? && Array(t.from).include?(state) }
+
+          findings << 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
+
+        findings
+      end
+
+      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
+
+      # default, every declared target, and every declared from — a
+      # from-only state (declared nowhere as a target) is real and is
+      # exactly the hole `Lifecycle#states` leaves: it answers default
+      # plus targets only.
+      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, from wherever the machine is ; a
+      # constrained one fires once any of its named sources is reached.
+      def reachable_states(lifecycle)
+        reached = Set.new([lifecycle.default])
+        loop do
+          grown = false
+          lifecycle.transitions.each do |_, transition|
+            next if reached.include?(transition.target)
+            next if transition.constrained? && Array(transition.from).none? { |source| reached.include?(source) }
+
+            reached << transition.target
+            grown = true
+          end
+          break unless grown
+        end
+        reached
+      end
+
+      # A state with no OUTGOING declared path at all is exempt from the
+      # stuck-state WARNING for a different reason than "it fires an
+      # unconstrained transition" — the default state of a lifecycle
+      # with only constrained transitions is legitimately allowed to sit
+      # forever, since nothing about *entering* it via default implies
+      # anything must eventually move it, unlike a state a transition
+      # explicitly delivered somewhere.
+      def terminal_exempt(_lifecycle) = []
+
+      # ── process managers / sagas ──────────────────────────────────────
+
+      def saga_findings(bluebook, pm)
+        findings = []
+        emitted  = emitted_events(bluebook)
+        verbs    = verbs_of(bluebook)
+
+        [pm.starts_on, pm.ends_on].compact.each do |event|
+          next if emitted.include?(bare(event))
+
+          findings << Finding.new(kind: :deaf_trigger, severity: :error, subject: pm.name,
+                                  message: "starts_on/ends_on names #{event.inspect}, which no command in this " \
+                                           "domain emits")
+        end
+
+        reached = pm_reachable_states(pm, emitted)
+        (Array(pm.states) - reached.to_a).each do |state|
+          findings << Finding.new(kind: :unreachable_pm_state, severity: :error, subject: pm.name,
+                                  message: "#{state.inspect} is declared but no handler chain from " \
+                                           "#{pm.states.first.inspect} ever reaches it")
+        end
+
+        pm.handlers.each do |handler|
+          # The compensating leg answers REFUSED, a synthetic trigger no
+          # command ever emits by name (ProcessManager::REFUSED) — not
+          # a deaf handler, the one handler this domain's own events can
+          # never satisfy on purpose.
+          if handler.event_type != ProcessManager::REFUSED && !emitted.include?(bare(handler.event_type))
+            findings << Finding.new(kind: :deaf_handler, severity: :error, subject: pm.name,
+                                    message: "a handler answers #{handler.event_type.inspect}, which no command " \
+                                             "in this domain emits")
+          end
+
+          handler.dispatches.each do |dispatch|
+            # SAME-DOMAIN, same as `SagaInterpreter#qualified` — a dispatch
+            # naming no domain at all (the ordinary shape a bare command
+            # constant now produces, S6) means THIS one, and is compared
+            # against `verbs_of`'s own fully-qualified spelling qualified
+            # the identical way, not left bare to miss it on a technicality.
+            qualified = dispatch.command_name.include?("::") ? dispatch.command_name : "#{bluebook.name}::#{dispatch.command_name}"
+            next if verbs.include?(qualified)
+
+            findings << Finding.new(kind: :unknown_dispatch, severity: :error, subject: pm.name,
+                                    message: "dispatches #{dispatch.command_name.inspect}, which this domain " \
+                                             "declares no command at — cross-domain dispatch is out of this " \
+                                             "checker's scope, same as CommandRules#resolve_references")
+          end
+        end
+
+        if pm.saga? && !reached.include?(pm.saga.from_state)
+          findings << Finding.new(kind: :dead_compensation, severity: :error, subject: pm.name,
+                                  message: "the compensation leaves #{pm.saga.from_state.inspect}, which no " \
+                                           "handler chain ever reaches — a refusal here can never fire it")
+        end
+
+        findings
+      end
+
+      # A handler edge is only usable in the closure if it can actually
+      # FIRE — REFUSED always can (it is a compensation trigger, not an
+      # event), and any other handler needs its event genuinely emitted.
+      # Without this, a deaf handler's declared from_state -> to_state
+      # pair reads as connected even though nothing can ever traverse
+      # it, which would hide exactly the states this walk exists to
+      # catch (a state only "reachable" through a handler that itself
+      # never fires).
+      def pm_reachable_states(pm, emitted)
+        return Set.new if Array(pm.states).empty?
+
+        reached = Set.new([pm.states.first])
+        loop do
+          grown = false
+          pm.handlers.each do |handler|
+            next unless handler.event_type == ProcessManager::REFUSED || emitted.include?(bare(handler.event_type))
+            next unless reached.include?(handler.from_state)
+            next if reached.include?(handler.to_state)
+
+            reached << handler.to_state
+            grown = true
+          end
+          break unless grown
+        end
+        reached
+      end
+
+      # ── policies ───────────────────────────────────────────────────────
+
+      def policy_findings(bluebook, policy)
+        return [] if policy.target_domain # cross-domain: CommandRules skips it too; so does this checker.
+
+        emitted = emitted_events(bluebook)
+        findings = []
+
+        # `policy.event_name` (Naming.unqualified) — NOT `bare`, which only
+        # strips a "::" domain qualifier. An AGGREGATE-scoped policy's
+        # `on_event` carries a "." aggregate qualifier instead (PolicyBuilder
+        # stores whatever was typed, verbatim — see `on "Account.
+        # AccountFrozen"`), and `bare` left it untouched, silently comparing
+        # "Account.AccountFrozen" against a list of bare emitted names that
+        # can never contain it. Latent until now : banking's one aggregate-
+        # scoped same-domain policy check would have caught it, but its only
+        # prior aggregate-scoped policy (ReviewOnFreeze) is also cross-domain
+        # (`across "Compliance"`), which exits this method one line above
+        # before the mismatch is ever reached.
+        unless emitted.include?(policy.event_name)
+          findings << Finding.new(kind: :deaf_policy, severity: :error, subject: policy.name,
+                                  message: "on #{policy.on_event.inspect}, which no command in this domain emits")
+        end
+
+        # `trigger` is spelled "Aggregate.Command" (or "Entity.Command" one
+        # level down), completed to an FQN by PolicyInterpreter#deliver as
+        # "#{domain}::#{trigger_command}" — the same join `verbs_of` builds
+        # independently, so the two spellings have to be compared as FQNs,
+        # never as bare command names.
+        unless verbs_of(bluebook).include?("#{bluebook.name}::#{policy.trigger_command}")
+          findings << Finding.new(kind: :unknown_trigger, severity: :error, subject: policy.name,
+                                  message: "trigger #{policy.trigger_command.inspect} resolves to no command " \
+                                           "this domain declares")
+        end
+
+        findings
+      end
+
+      # ── shared enumeration ────────────────────────────────────────────
+
+      # A PORT OPERATION EMITS TOO — the primary/driving port an adapter
+      # outside the bluebook calls through (see hecksagon_builder.rb) is a
+      # second, real source of events, alongside a command's own `emits`.
+      # Ports attach to the aggregate/bluebook from the SIBLING `.hecksagon`
+      # file, not this one — a caller that boots only the `.bluebook` (as
+      # the fixtures under spec/fixtures/model_check/ do, having no
+      # hecksagon at all) simply finds none, which is correct : nothing
+      # can be deaf to an event that isn't even wired up yet.
+      def emitted_events(bluebook)
+        aggregate_emits = bluebook.aggregates.flat_map do |aggregate|
+          aggregate.commands.map(&:emits) +
+            aggregate.entities.flat_map { |entity| entity.commands.map(&:emits) } +
+            aggregate.ports.flat_map { |port| port.operations.map(&:emits) }
+        end
+        chapter_emits = bluebook.ports.flat_map { |port| port.operations.map(&:emits) }
+
+        (aggregate_emits + chapter_emits).flatten.uniq
+      end
+
+      # Fully-qualified, the same spelling DispatchSpec#command_name
+      # carries and fuzzing/sequence_generator/catalog.rb builds
+      # independently for the same reason: a saga dispatch and a fuzzer
+      # step both have to name a verb the same way the door does.
+      def verbs_of(bluebook)
+        bluebook.aggregates.flat_map do |aggregate|
+          verbs = aggregate.commands.map { |command| "#{bluebook.name}::#{aggregate.hecks_name}.#{command.hecks_name}" }
+          verbs + aggregate.entities.flat_map do |entity|
+            entity.commands.map { |command|
+              "#{bluebook.name}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
+            }
+          end
+        end
+      end
+
+      def bare(event) = event.to_s.split("::").last
+    end
+  end
+end

data/lib/hecks/bluebook/pattern_subset.rb

@@ -0,0 +1,120 @@
+module Hecks
+  module Bluebook
+    # WHICH REGEXES A BLUEBOOK MAY SAY.
+    #
+    # A `pattern:` is a fact about a value, carried in a bluebook — declared
+    # data, not Ruby code, so it must not lean on what any one engine happens
+    # to accept. Regex engines disagree in two different ways :
+    #
+    #   ONLY A BACKTRACKING ENGINE CAN MATCH IT — lookahead, lookbehind,
+    #   backreferences, atomic groups, possessive quantifiers. None of these
+    #   can be matched in linear time, and linear-time engines refuse them
+    #   outright. Refused here for the same reason.
+    #
+    #   EVERY ENGINE PARSES IT AND THEY MEAN DIFFERENT THINGS — the dangerous
+    #   half, because nothing errors. `\d` `\w` `\s` are ASCII in some engines
+    #   and Unicode in others ; `[:digit:]` and friends flip the same way in
+    #   the other direction. Both families are refused, and a domain spells
+    #   the range it means.
+    #
+    # What remains — explicit ranges, alternation, quantifiers, anchors,
+    # groups — reads identically everywhere, with `^` and `$` as LINE anchors
+    # (Ruby's reading). The evidence is spec/corpus/fixtures/patterns.json.
+    module PatternSubset
+      Rejection = Struct.new(:construct, :reason)
+
+      REASONS = {
+        backreference:
+                             "backreferences cannot be matched in linear time and portable " \
+                             "engines refuse them ; a declared pattern may not depend on one",
+        named_backreference:
+                             "a named backreference is still a backreference — it cannot be " \
+                             "matched in linear time ; a declared pattern may not depend on one",
+        perl_class:
+                             "engines read it in OPPOSITE directions : ASCII in some and " \
+                             "Unicode in others, so an Arabic-Indic digit satisfies one and not " \
+                             "the other. Spell the range you mean — [0-9], [A-Za-z0-9_], [ \t] " \
+                             "— which every engine reads the same way",
+        posix_class:
+                             "[:digit:] and friends flip between ASCII and Unicode across " \
+                             "engines — the mirror of the perl classes, and wrong in the same " \
+                             "way. Spell the range you mean",
+        lookahead:
+                             "lookahead cannot be matched in linear time and portable engines " \
+                             "refuse it ; a declared pattern may not depend on it",
+        lookbehind:
+                             "lookbehind cannot be matched in linear time and portable engines " \
+                             "refuse it ; a declared pattern may not depend on it",
+        atomic_group:
+                             "an atomic group is a backtracking-engine control knob — " \
+                             "linear-time engines reject `(?>` as a syntax error",
+        possessive:
+                             "a possessive quantifier is a backtracking-engine control knob — " \
+                             "linear-time engines reject it as a syntax error"
+      }.freeze
+
+      module_function
+
+      # nil when the pattern is admitted, a Rejection when it is not.
+      #
+      # A CHARACTER WALK, deliberately plain : the subset is defined by this
+      # walk, and a cleverer spelling would hide what it admits. An escaped
+      # construct is a LITERAL, not a violation — `\(\?=` is the three
+      # characters "(?=" and says nothing about lookahead — which is why this
+      # steps over each backslash pair rather than matching the pattern as a
+      # whole.
+      def validate(pattern)
+        chars = pattern.to_s.chars
+        index = 0
+
+        while index < chars.length
+          if chars[index] == "\\"
+            nxt = chars[index + 1]
+            return refuse(:backreference)        if nxt&.match?(/[1-9]/)
+            return refuse(:named_backreference)  if %w[k g].include?(nxt)
+            return refuse(:perl_class)           if %w[d D w W s S].include?(nxt)
+
+            index += nxt ? 2 : 1
+            next
+          end
+
+          if chars[index] == "(" && chars[index + 1] == "?"
+            return refuse(:lookahead)    if %w[= !].include?(chars[index + 2])
+            return refuse(:lookbehind)   if chars[index + 2] == "<" && %w[= !].include?(chars[index + 3])
+            return refuse(:atomic_group) if chars[index + 2] == ">"
+          end
+
+          return refuse(:posix_class)  if posix_class_at?(chars, index)
+          return refuse(:possessive)   if %w[* + ?].include?(chars[index]) && chars[index + 1] == "+"
+
+          index += 1
+        end
+
+        nil
+      end
+
+      # SPELLED OUT, not derived from the key : these strings are the refusal
+      # a caller reads.
+      CONSTRUCTS = {
+        backreference:       "backreference",
+        named_backreference: "named backreference",
+        perl_class:          "perl character class",
+        posix_class:         "posix bracket class",
+        lookahead:           "lookahead",
+        lookbehind:          "lookbehind",
+        atomic_group:        "atomic group",
+        possessive:          "possessive quantifier"
+      }.freeze
+
+      def refuse(key) = Rejection.new(CONSTRUCTS.fetch(key), REASONS.fetch(key))
+
+      def posix_class_at?(chars, index)
+        return false unless chars[index] == "[" && chars[index + 1] == ":"
+
+        cursor = index + 2
+        cursor += 1 while chars[cursor]&.match?(/[a-zA-Z]/)
+        chars[cursor] == ":" && chars[cursor + 1] == "]"
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/policy.rb

@@ -0,0 +1,41 @@
+# GENERATED — projected from the language's own Policy aggregate.
+# DO NOT EDIT: the holding half is rendered, and Behaviour::Policy
+# is where anything hand-written belongs.
+require_relative "behaviour/policy"
+
+module Hecks
+  module Bluebook
+    class Policy
+      include Hecks::IR
+      include Behaviour::Policy
+
+      emits_ir(
+        name:            :name,
+        on_event:        :on_event,
+        trigger_command: :trigger_command,
+        target_domain:   :target_domain,
+        where:           :where,
+        for_each:        :for_each,
+        with_spec:       -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }
+      )
+
+      attr_reader :name, :on_event, :trigger_command, :target_domain, :where, :for_each, :with_spec
+
+      # AGGREGATE, DECLARED AND DELIBERATELY OFF THE WIRE
+      # the wire format is a pinned contract, and it does not carry
+      # where a policy was written before the builder hoisted it
+      attr_accessor :aggregate
+
+      def initialize(name:, on_event: nil, trigger_command: nil, target_domain: nil, where: nil, for_each: nil, with_spec: [], aggregate: nil)
+        @name = name.to_s
+        @on_event = on_event
+        @trigger_command = trigger_command
+        @target_domain = target_domain
+        @where = where
+        @for_each = for_each
+        @with_spec = with_spec
+        @aggregate = aggregate&.to_s
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/process_manager.rb

@@ -0,0 +1,86 @@
+require_relative "behaviour/process_manager"
+require_relative "../ir"
+
+module Hecks
+  module Bluebook
+    DispatchSpec = Struct.new(:command_name, :with_spec, keyword_init: true) do
+      # A Struct already answers to_h; including the mixin puts the
+      # DECLARED emission ahead of Struct's own in the ancestry, which
+      # is what makes the shape data rather than a method body.
+      include Hecks::IR
+
+      emits_ir(
+        command_name: -> { command_name.to_s },
+        with_spec:    -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }
+      )
+    end
+
+    ProcessManagerHandler = Struct.new(:event_type, :from_state, :to_state,
+                                       :dispatches, keyword_init: true) do
+      include Hecks::IR
+
+      emits_ir(
+        event_type: -> { event_type.to_s },
+        from_state: -> { from_state.to_s },
+        to_state:   -> { to_state.to_s },
+        dispatches: many(:dispatches)
+      )
+    end
+
+    # The compensation half of a procedure, as its own thing.
+    #
+    # A PROCESS MANAGER coordinates: legs, states, an opinion about who goes
+    # next. A SAGA undoes: what makes the world good again when a leg it
+    # dispatched is refused. Two concepts, and the industry slurs them into one
+    # word — so here they are two objects, and a procedure either has a saga or
+    # does not.
+    #
+    # `undoes` is the ordered list of commands the compensation sends. Today that
+    # order is the AUTHOR's, written by hand in one `on :refused` leg, and the
+    # runtime does not know which legs actually completed. When compensation
+    # moves beside each dispatch — `reverses` on the step it reverses — this is
+    # where the completed ones, newest first, will live. The shape is already
+    # right for it; only the source of the order changes.
+    Saga = Struct.new(:trigger, :from_state, :to_state, :reversals, keyword_init: true) do
+      def undoes = reversals.map(&:command_name)
+
+      def to_s = "#{trigger} → #{to_state} (#{undoes.join(', ')})"
+    end
+
+    class ProcessManager
+      # The BLUEBOOK's name for this construct, asked the same way of a class
+      # that has crossed over and of an IR object that has not. Collapses into
+      # Construct when this one crosses.
+      # The trigger of a compensating leg. Not an event name — no aggregate
+      # announces that a leg the procedure dispatched was declined — so it lives
+      # here beside the thing it triggers rather than in the runtime that
+      # notices it. Declared in the language's Trigger vocabulary, which
+      # spec/vocabulary_conformance_spec holds to this constant.
+      REFUSED = Hecks::Vocabulary.fetch("Trigger").first
+
+      include Hecks::IR
+      include Behaviour::ProcessManager
+
+      emits_ir(
+        name:          :name,
+        correlates_by: -> { correlates_by.to_s },
+        starts_on:     :starts_on,
+        ends_on:       :ends_on,
+        states:        :states,
+        handlers:      many(:handlers)
+      )
+
+      attr_reader :name, :correlates_by, :starts_on, :ends_on, :states, :handlers
+
+      def initialize(name:, correlates_by: nil, starts_on: nil, ends_on: nil,
+                     states: [], handlers: [])
+        @name          = name.to_s
+        @correlates_by = correlates_by
+        @starts_on     = starts_on
+        @ends_on       = ends_on
+        @states        = states
+        @handlers      = handlers
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/project_discovery.rb

@@ -0,0 +1,30 @@
+require "find"
+
+module Hecks
+  module Bluebook
+    # Finds domain declaration folders without loading or executing them.
+    class ProjectDiscovery
+      SKIPPED_DIRECTORIES = %w[.git .bundle data node_modules target tmp vendor generated coverage].freeze
+
+      attr_reader :root
+
+      def initialize(root)
+        @root = File.expand_path(root)
+      end
+
+      def bluebook_directories
+        found = []
+        Find.find(root) do |path|
+          if File.directory?(path)
+            if SKIPPED_DIRECTORIES.include?(File.basename(path))
+              Find.prune
+            elsif File.basename(path) == "bluebook" && Dir.glob(File.join(path, "*.bluebook")).any?
+              found << path
+            end
+          end
+        end
+        found.sort
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/project_loader.rb

@@ -0,0 +1,40 @@
+require_relative "project_discovery"
+require_relative "project_register"
+
+module Hecks
+  module Bluebook
+    # Boots each discovered directory and feeds its declarations into the
+    # deterministic project register. Discovery and FQN registration live in
+    # their own objects so either can be used without executing domains.
+    class ProjectLoader
+      Entry          = ProjectRegister::Entry
+      DuplicateFqn   = ProjectRegister::DuplicateFqn
+      MissingRealm   = ProjectRegister::MissingRealm
+      LatestMismatch = ProjectRegister::LatestMismatch
+
+      attr_reader :root, :discovery, :register
+
+      def self.load(root) = new(root).load
+
+      def initialize(root, discovery: ProjectDiscovery.new(root), register: ProjectRegister.new)
+        @root      = File.expand_path(root)
+        @discovery = discovery
+        @register  = register
+      end
+
+      def load
+        discovery.bluebook_directories.each do |directory|
+          runtime = Runtime.boot(directory)
+          register.register(runtime.registry.bluebooks.values, runtime.registry, runtime, directory)
+        end
+        self
+      end
+
+      def entries = register.entries
+      def fetch(address) = register.fetch(address)
+      def include?(address) = register.include?(address)
+      def commands = register.commands
+      def queries  = register.queries
+    end
+  end
+end