hecks 1.0.2 → 1.2.0

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

@@ -82,8 +82,26 @@ module Hecks
           Array(t.aggregates).each { |aggregate| judge_aggregate(t, aggregate) }
         end
 
+        # One Declare, then one AddX pass per rule collection the aggregate
+        # carries — each pass is independent of the others (they mutate
+        # different fields), so each is its own private method below; only
+        # Declare-before-any-Add is order-sensitive, and that order is
+        # preserved here.
         def judge_aggregate(translation, aggregate)
           name = aggregate.name
+          declare_aggregate(translation, aggregate, name)
+
+          judge_renames(aggregate, name)
+          judge_moves(aggregate, name)
+          judge_converts(aggregate, name)
+          judge_drops(aggregate, name)
+          judge_retypes(aggregate, name)
+          judge_computes(aggregate, name)
+          judge_rekeys(aggregate, name)
+          judge_backfills(aggregate, name)
+        end
+
+        def declare_aggregate(translation, aggregate, name)
           parent = {
             domain: v(translation.domain),
             from:   v(translation.from),
@@ -91,45 +109,66 @@ module Hecks
           }
           send_to("Translation::TranslationAggregate.Declare", name,
                   with: { translation_ref: parent, name: v(name), was: v(aggregate.was) })
+        end
 
+        def judge_renames(aggregate, name)
           Hash(aggregate.renames).each do |from, to|
             send_to("Translation::TranslationAggregate.AddRename", name, to:   name,
                                                                          with: { from: v(from), to: v(to) })
           end
+        end
 
+        def judge_moves(aggregate, name)
           Array(aggregate.moves).each do |move|
             send_to("Translation::TranslationAggregate.AddMove", name, to:   name,
                                                                        with: { from: v(move.from), to: v(move.to) })
           end
+        end
 
+        def judge_converts(aggregate, name)
           Array(aggregate.converts).each do |convert|
             send_to("Translation::TranslationAggregate.AddConvert", name, to:   name,
-                                                                          with: { from: v(convert.from), to: v(convert.to), values: v(convert.values.inspect) })
+                                                                          with: { from:   v(convert.from),
+                                                                                  to:     v(convert.to),
+                                                                                  values: v(convert.values.inspect) })
           end
+        end
 
+        def judge_drops(aggregate, name)
           Array(aggregate.drops).each do |dropped|
             send_to("Translation::TranslationAggregate.AddDrop", name, to:   name,
                                                                        with: { value: v(dropped) })
           end
+        end
 
+        def judge_retypes(aggregate, name)
           Array(aggregate.retypes).each do |retype|
             send_to("Translation::TranslationAggregate.AddRetype", name, to:   name,
                                                                          with: { from: v(retype.from), to: v(retype.to) })
           end
+        end
 
+        def judge_computes(aggregate, name)
           Array(aggregate.computes).each do |compute|
             send_to("Translation::TranslationAggregate.AddCompute", name, to:   name,
-                                                                          with: { from: v(compute.from), to: v(compute.to), sql: v(compute.sql) })
+                                                                          with: { from: v(compute.from),
+                                                                                  to:   v(compute.to),
+                                                                                  sql:  v(compute.sql) })
           end
+        end
 
+        def judge_rekeys(aggregate, name)
           Array(aggregate.rekeys).each do |rekey|
             send_to("Translation::TranslationAggregate.AddRekey", name, to:   name,
                                                                         with: { sql: v(rekey.sql) })
           end
+        end
 
+        def judge_backfills(aggregate, name)
           Array(aggregate.backfills).each do |backfill|
             send_to("Translation::TranslationAggregate.AddBackfill", name, to:   name,
-                                                                           with: { name: v(backfill.name), default: v(backfill.default.inspect) })
+                                                                           with: { name:    v(backfill.name),
+                                                                                   default: v(backfill.default.inspect) })
           end
         end
       end

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

@@ -21,7 +21,7 @@ module Hecks
 
         def v(text) = text.nil? ? nil : { value: text.to_s }
 
-        def args(pairs) = pairs.reject { |_, value| value.nil? }
+        def args(pairs) = pairs.compact
 
         def offer(label)
           yield

data/lib/hecks/bluebook/meta_validator.rb

@@ -52,11 +52,11 @@ module Hecks
       # concept file requires no second catalog here; deterministic filename
       # order is the source order exported to IR.
       GRAMMAR_DIR   = File.expand_path("../language/bluebook", __dir__).freeze
-      GRAMMAR_FILES = Dir.glob(File.join(GRAMMAR_DIR, "*.bluebook")).sort.freeze
+      GRAMMAR_FILES = Dir.glob(File.join(GRAMMAR_DIR, "*.bluebook")).freeze
       # Sibling artifact languages use the same folder-is-the-chapter rule.
       # Their arrays are discovered, sorted source sets—not filename catalogs.
-      WORLD_GRAMMAR = Dir.glob(File.expand_path("../language/world/*.bluebook", __dir__)).sort.freeze
-      HECKSAGON_GRAMMAR = Dir.glob(File.expand_path("../language/hecksagon/*.bluebook", __dir__)).sort.freeze
+      WORLD_GRAMMAR = Dir.glob(File.expand_path("../language/world/*.bluebook", __dir__)).freeze
+      HECKSAGON_GRAMMAR = Dir.glob(File.expand_path("../language/hecksagon/*.bluebook", __dir__)).freeze
       # so is a port — whole-project table-unification survey, item #13's
       # remaining builders. Backs the new PortJudge door the same way
       # WORLD_GRAMMAR backs WorldJudge.
@@ -65,7 +65,7 @@ module Hecks
       ADAPTER_GRAMMAR = File.expand_path("../language/adapter.bluebook", __dir__).freeze
       # so is a translation — same reasoning, one file over. Backs
       # TranslationJudge.
-      TRANSLATION_GRAMMAR = Dir.glob(File.expand_path("../language/translation/*.bluebook", __dir__)).sort.freeze
+      TRANSLATION_GRAMMAR = Dir.glob(File.expand_path("../language/translation/*.bluebook", __dir__)).freeze
 
       # ADR 0026's OWN SEAM: THE CORE DOES NOT NAME ITS EXTENSION POINTS.
       #
@@ -483,7 +483,7 @@ module Hecks
       # is added there.
       def self.load_attached_grammar_into(registry)
         Hecks.with_registry(registry) do
-          Dir.glob(File.join(ATTACHED_GRAMMAR_DIR, "*.bluebook")).sort.each { |file| Kernel.load(file) }
+          Dir.glob(File.join(ATTACHED_GRAMMAR_DIR, "*.bluebook")).each { |file| Kernel.load(file) }
         end
       end
 

data/lib/hecks/bluebook/model_check.rb

@@ -1,5 +1,3 @@
-require "set"
-
 module Hecks
   module Bluebook
     # Lightweight formal methods over the IR — the same family as TLA+/
@@ -89,7 +87,7 @@ module Hecks
           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.process_managers.each { |process_manager| findings.concat(saga_findings(bluebook, process_manager)) }
         bluebook.policies.each { |policy| findings.concat(policy_findings(bluebook, policy, hecksagon, known_domains)) }
         findings
       end
@@ -103,38 +101,46 @@ module Hecks
         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")
+        findings = []
+        findings.concat(unknown_transition_commands(lifecycle, commands, subject))
+        findings.concat(unreachable_state_findings(lifecycle, full, reached, subject))
+        findings.concat(dead_transition_findings(lifecycle, reached, subject))
+        findings.concat(stuck_state_findings(lifecycle, reached, subject))
+        findings
+      end
+
+      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
 
-        lifecycle.transitions.each do |command, transition|
+      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) }
 
-          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")
+          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
 
+      def stuck_state_findings(lifecycle, reached, subject)
         any_unconstrained = lifecycle.transitions.any? { |_, t| !t.constrained? }
-        (reached - terminal_exempt(lifecycle)).each do |state|
+        (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) }
 
-          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")
+          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)
@@ -165,6 +171,11 @@ module Hecks
         reached = Set.new([lifecycle.default])
         loop do
           grown = false
+          # `transitions` is an Array of [from, transition]-shaped entries
+          # (Lifecycle#transitions), not a Hash — Style/HashEachMethods'
+          # `each_value` rewrite assumed otherwise from the block shape
+          # alone. False positive.
+          # rubocop:disable-next Style/HashEachMethods
           lifecycle.transitions.each do |_, transition|
             next if reached.include?(transition.target)
             next if transition.constrained? && Array(transition.from).none? { |source| reached.include?(source) }
@@ -202,79 +213,105 @@ module Hecks
 
       # ── process managers / sagas ──────────────────────────────────────
 
-      def saga_findings(bluebook, pm)
+      def saga_findings(bluebook, process_manager)
+        emitted = emitted_events(bluebook)
+        verbs   = verbs_of(bluebook)
+        reached = pm_reachable_states(process_manager, emitted)
+
         findings = []
-        emitted  = emitted_events(bluebook)
-        verbs    = verbs_of(bluebook)
+        findings.concat(deaf_trigger_findings(process_manager, emitted))
+        findings.concat(unreachable_pm_state_findings(process_manager, reached))
+        process_manager.handlers.each do |handler|
+          findings.concat(handler_findings(bluebook, process_manager, emitted, verbs, handler))
+        end
+        findings.concat(dead_compensation_findings(process_manager, reached))
+        findings
+      end
 
-        [pm.starts_on, pm.ends_on].compact.each do |event|
+      def deaf_trigger_findings(process_manager, emitted)
+        [process_manager.starts_on, process_manager.ends_on].compact.filter_map 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")
+          Finding.new(kind: :deaf_trigger, severity: :error, subject: process_manager.name,
+                      message: "starts_on/ends_on names #{event.inspect}, which no command in this " \
+                               "domain emits")
         end
+      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")
+      def unreachable_pm_state_findings(process_manager, reached)
+        (Array(process_manager.states) - reached.to_a).map do |state|
+          Finding.new(kind: :unreachable_pm_state, severity: :error, subject: process_manager.name,
+                      message: "#{state.inspect} is declared but no handler chain from " \
+                               "#{process_manager.states.first.inspect} ever reaches it")
         end
+      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
+      # ONE HANDLER'S OWN FINDINGS — deaf_handler, unknown_dispatch (one
+      # per dispatch), and unarmed_compensation (one per compensating
+      # dispatch), pulled out of saga_findings' own handler loop; each
+      # check reads only this handler plus the domain-wide emitted/verbs
+      # sets saga_findings already resolved once, no state shared BETWEEN
+      # handlers.
+      def handler_findings(bluebook, process_manager, emitted, verbs, handler)
+        findings = []
 
-          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
+        # 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: process_manager.name,
+                                  message: "a handler answers #{handler.event_type.inspect}, which no command " \
+                                           "in this domain emits")
+        end
 
-          # A `compensates` DECLARED WITH NOWHERE TO EVER FIRE — the exact
-          # shape of the real bug this whole feature closes ("the
-          # reversal was written and never armed"), caught at build/
-          # model-check time instead of discovered in production. No
-          # handler anywhere answers REFUSED (`pm.saga?` false) means
-          # `SagaInterpreter#unwind` never runs for this process
-          # manager at all, so a declared `compensates` is structurally
-          # unreachable — not a warning about style, a dead declaration.
-          if !pm.saga? && handler.dispatches.any?(&:compensates)
-            handler.dispatches.select(&:compensates).each do |dispatch|
-              findings << Finding.new(kind: :unarmed_compensation, severity: :error, subject: pm.name,
-                                      message: "#{dispatch.command_name} compensates #{dispatch.compensates.command_name}, " \
-                                               "but no handler anywhere in this saga answers a refusal — the " \
-                                               "compensation is declared and can never fire")
-            end
-          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 = if dispatch.command_name.include?("::")
+                        dispatch.command_name
+                      else
+                        "#{bluebook.name}::#{dispatch.command_name}"
+                      end
+          next if verbs.include?(qualified)
+
+          findings << Finding.new(kind: :unknown_dispatch, severity: :error, subject: process_manager.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
 
-        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")
+        # A `compensates` DECLARED WITH NOWHERE TO EVER FIRE — the exact
+        # shape of the real bug this whole feature closes ("the
+        # reversal was written and never armed"), caught at build/
+        # model-check time instead of discovered in production. No
+        # handler anywhere answers REFUSED (`process_manager.saga?` false) means
+        # `SagaInterpreter#unwind` never runs for this process
+        # manager at all, so a declared `compensates` is structurally
+        # unreachable — not a warning about style, a dead declaration.
+        if !process_manager.saga? && handler.dispatches.any?(&:compensates)
+          handler.dispatches.select(&:compensates).each do |dispatch|
+            findings << Finding.new(kind: :unarmed_compensation, severity: :error, subject: process_manager.name,
+                                    message: "#{dispatch.command_name} compensates #{dispatch.compensates.command_name}, " \
+                                             "but no handler anywhere in this saga answers a refusal — the " \
+                                             "compensation is declared and can never fire")
+          end
         end
 
         findings
       end
 
+      def dead_compensation_findings(process_manager, reached)
+        return [] unless process_manager.saga? && !reached.include?(process_manager.saga.from_state)
+
+        [Finding.new(kind: :dead_compensation, severity: :error, subject: process_manager.name,
+                     message: "the compensation leaves #{process_manager.saga.from_state.inspect}, which no " \
+                              "handler chain ever reaches — a refusal here can never fire it")]
+      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.
@@ -283,13 +320,13 @@ module Hecks
       # 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?
+      def pm_reachable_states(process_manager, emitted)
+        return Set.new if Array(process_manager.states).empty?
 
-        reached = Set.new([pm.states.first])
+        reached = Set.new([process_manager.states.first])
         loop do
           grown = false
-          pm.handlers.each do |handler|
+          process_manager.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)
@@ -446,9 +483,9 @@ module Hecks
         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|
+            entity.commands.map do |command|
               "#{bluebook.name}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
-            }
+            end
           end
         end
       end

data/lib/hecks/bluebook/pattern_subset.rb

@@ -63,6 +63,15 @@ module Hecks
       # characters "(?=" and says nothing about lookahead — which is why this
       # steps over each backslash pair rather than matching the pattern as a
       # whole.
+      # One character walk is the subset's DEFINITION (see the method
+      # comment above): each construct-check is a branch in a single
+      # ordered pass sharing `index`/`in_class`/`class_start`. Splitting
+      # the branches into separate methods would force those three cursor
+      # variables to thread as parameters/return values between them,
+      # turning "the subset is this walk" into "the subset is these
+      # methods agreeing about a shared cursor" — exactly what the walk's
+      # own comment says a cleverer spelling would obscure.
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def validate(pattern)
         chars = pattern.to_s.chars
         index = 0

data/lib/hecks/bluebook/policy.rb

@@ -16,7 +16,8 @@ module Hecks
         target_domain:   :target_domain,
         where:           :where,
         for_each:        :for_each,
-        with_spec:       -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }
+        with_spec:       -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
+        where_ast:       -> { where_ast }
       )
 
       attr_reader :name, :on_event, :trigger_command, :target_domain, :where, :for_each, :with_spec

data/lib/hecks/bluebook/process_manager.rb

@@ -74,6 +74,12 @@ module Hecks
       def to_s = "#{trigger} → #{to_state} (#{undoes.join(', ')})"
     end
 
+    # The built form of a `process_manager "Name" do ... end` block,
+    # produced by `DSL::ProcessManagerBuilder` — its start/end events,
+    # correlation field, derived states, and handler rows. Its
+    # compensation half (`saga`, `Behaviour::ProcessManager#saga`) is
+    # DERIVED from the handler answering `REFUSED`, below, not declared as
+    # its own construct.
     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

data/lib/hecks/bluebook/project_register.rb

@@ -35,34 +35,56 @@ module Hecks
                   "#{bluebook.name} in #{directory} declares latest #{world.latest.inspect}, not #{bluebook.version.inspect}"
           end
 
-          bluebook.aggregates.each do |aggregate|
-            aggregate.commands.each do |command|
-              add(Fqn.command(realm: realm, domain: bluebook.name, version: bluebook.version,
-                              aggregate: aggregate.hecks_name, command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version) if bluebook.version
-              add(Fqn.command(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
-                              command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version) if current?(
-                                bluebook, world
-                              )
-            end
-            aggregate.queries.each do |query|
-              name = Naming.snake(query.name)
-              add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
-                            aggregate: aggregate.hecks_name, query: name), directory, dispatcher, query.name, bluebook.version) if bluebook.version
-              add(Fqn.query(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
-                            query: name), directory, dispatcher, query.name, bluebook.version) if current?(bluebook, world)
-            end
+          bluebook.aggregates.each { |aggregate| register_aggregate!(aggregate, bluebook, world, realm, directory, dispatcher) }
+          bluebook.read_models.each { |model| register_read_model!(model, bluebook, world, realm, directory, dispatcher) }
+        end
+        self
+      end
+
+      private
+
+      # Split out of `register` per-aggregate: same versioned-then-current
+      # registration shape as `register_read_model!`, just applied to a
+      # command/query pair instead of a single report. No state threads
+      # back to `register` — each `add` call is independent.
+      def register_aggregate!(aggregate, bluebook, world, realm, directory, dispatcher)
+        aggregate.commands.each do |command|
+          if bluebook.version
+            add(Fqn.command(realm: realm, domain: bluebook.name, version: bluebook.version,
+                            aggregate: aggregate.hecks_name, command: command.hecks_name),
+                directory, dispatcher, command.hecks_name, bluebook.version)
           end
-          bluebook.read_models.each do |model|
+          if current?(bluebook, world)
+            add(Fqn.command(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
+                            command: command.hecks_name), directory, dispatcher, command.hecks_name, bluebook.version)
+          end
+        end
+        aggregate.queries.each do |query|
+          name = Naming.snake(query.name)
+          if bluebook.version
             add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
-                          query: model.query_name), directory, dispatcher, model.query_name, bluebook.version) if bluebook.version
-            add(Fqn.query(realm: realm, domain: bluebook.name, query: model.query_name),
-                directory, dispatcher, model.query_name, bluebook.version) if current?(bluebook, world)
+                          aggregate: aggregate.hecks_name, query: name), directory, dispatcher, query.name, bluebook.version)
+          end
+          if current?(bluebook, world)
+            add(Fqn.query(realm: realm, domain: bluebook.name, aggregate: aggregate.hecks_name,
+                          query: name), directory, dispatcher, query.name, bluebook.version)
           end
         end
-        self
       end
 
-      private
+      # Split out of `register` per-read-model: registers the versioned FQN
+      # (if this bluebook declares a version) and the current/unversioned
+      # FQN (if this bluebook is the world's latest) for one report.
+      def register_read_model!(model, bluebook, world, realm, directory, dispatcher)
+        if bluebook.version
+          add(Fqn.query(realm: realm, domain: bluebook.name, version: bluebook.version,
+                        query: model.query_name), directory, dispatcher, model.query_name, bluebook.version)
+        end
+        if current?(bluebook, world)
+          add(Fqn.query(realm: realm, domain: bluebook.name, query: model.query_name),
+              directory, dispatcher, model.query_name, bluebook.version)
+        end
+      end
 
       # THE ACTUAL "more than one tenant" MOMENT — Runtime::TenantCheck's
       # own header names this table as the one place real multitenancy
@@ -93,9 +115,7 @@ module Hecks
 
       def add(fqn, directory, dispatcher, declared_verb, domain_version)
         existing = entries[fqn.to_s]
-        if existing
-          raise DuplicateFqn, "#{fqn} is declared in both #{existing.source_directory} and #{directory}"
-        end
+        raise DuplicateFqn, "#{fqn} is declared in both #{existing.source_directory} and #{directory}" if existing
 
         entries[fqn.to_s] = Entry.new(
           fqn: fqn, source_directory: directory, dispatcher: dispatcher,

data/lib/hecks/bluebook/query.rb

@@ -1,6 +1,10 @@
 require_relative "behaviour/query"
 
 module Hecks
+  # Reopened here only to add `render_value` below — the pinned
+  # wire-literal rendering (`Literal.render`) the `emits_ir` Procs
+  # throughout this chapter reach for. See lib/hecks/bluebook.rb's own
+  # header for what `Bluebook` is as a whole.
   module Bluebook
     def self.render_value(value) = Literal.render(value)
 

data/lib/hecks/bluebook/read_model.rb

@@ -35,8 +35,8 @@ module Hecks
       # `reference_target.nil?` stays a real, checkable fact for the
       # interpreter instead of silently becoming `""`.
       def initialize(name:, description: nil, reference_name: nil, reference_target: nil, aggregate_heads: [],
-                     group_by: [], count: nil, median_field: nil, **options)
-        super(joins: aggregate_heads, **options)
+                     group_by: [], count: nil, median_field: nil, **)
+        super(joins: aggregate_heads, **)
         @name             = name.to_s
         @hecks_name       = @name
         @description      = description

data/lib/hecks/bluebook/smoke_test.rb

@@ -118,6 +118,11 @@ module Hecks
       # the time that aggregate's own turn comes, the same reason
       # `Synthesizer#args_for`'s `created` map is threaded through in
       # this same order.
+      # `created` and `failures` thread through both the aggregate loop and the
+      # read_models loop below in the declaration order the comment above already
+      # documents; splitting would turn that ordering into an implicit contract on
+      # parameter/return passing instead of one visible sequence.
+      # rubocop:disable-next Metrics/AbcSize
       def smoke_domain(dispatcher, domain)
         chapter = dispatcher.registry.bluebook(domain)
         return [] unless chapter

data/lib/hecks/bluebook/synthesizer.rb

@@ -64,7 +64,8 @@ module Hecks
                        chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
         return "smoke-test" unless value_object
 
-        return value_object.members.first.to_h if value_object.respond_to?(:closed_set?) && value_object.closed_set? && value_object.members.any?
+        closed_set = value_object.respond_to?(:closed_set?) && value_object.closed_set? && value_object.members.any?
+        return value_object.members.first.to_h if closed_set
 
         value_object.attributes.to_h { |field| [field.name, field_value_for(chapter, aggregate, field.type)] }
       end

data/lib/hecks/bluebook/translation.rb

@@ -11,6 +11,9 @@ module Hecks
     # Paths follow `TranslationMove`'s convention (dotted reaches a VO
     # member); `values` maps every old-era value that can appear to its
     # new-era replacement.
+    # `:values` shadows Struct#values on purpose (same reasoning as
+    # AttributeCollector::OneOf) — no caller reads the built-in behavior.
+    # rubocop:disable-next Lint/StructNewOverride
     TranslationConvert = Struct.new(:from, :to, :values)
 
     # A value object's or entity's own TYPE NAME changed with its member