hecks 3.4.2 → 3.6.0

data/lib/hecks/runtime/value/validation.rb

@@ -0,0 +1,125 @@
+require_relative "../../bluebook/expression/evaluator"
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "invariant_violation"
+
+module Hecks
+  module Runtime
+    class Value
+      # What a value object's own fields pass through on construction: defaults, nested
+      # normalization, and the full set of boundary checks and invariants. Extended into `Value`
+      # beside `Coercion`.
+      module Validation
+        # `build`'s own recursive twin of `for_attribute`, normalizing a value
+        # object's own composite-typed fields into their declared shape.
+        #
+        # Stays a plain Hash, never a nested `Value` — `Value#with` depends on that.
+        #
+        # @param aggregate [Bluebook::Aggregate, Entity, nil] nested-type lookup scope
+        # @param value_object [Class] the value object `fields` belongs to
+        # @param fields [Hash{Symbol => Object}] the outer fields, already defaulted
+        # @return [Hash{Symbol => Object}] `fields` with composite fields normalized
+        # @raise [Runtime::TypeMismatch] if a nested field cannot be coerced
+        # @raise [Runtime::UnknownArgument] if a nested field names an undeclared key
+        # @raise [Runtime::InvariantViolation] if a nested field breaks its own invariant
+        def normalize_composite_fields(aggregate, value_object, fields)
+          return fields unless aggregate.respond_to?(:value_object)
+
+          value_object.attributes.each do |attribute|
+            next unless fields.key?(attribute.name)
+
+            normalize_composite_field(aggregate, attribute, fields)
+          end
+
+          fields
+        end
+
+        # Fills every declared attribute `fields` lacks with its own `default:`.
+        #
+        # @param value_object [Class] the `Bluebook::ValueObject` subclass whose
+        #   declared defaults are read
+        # @param fields [Hash{Symbol => Object}] the offered fields; written in place
+        # @return [Hash{Symbol => Object}] `fields`, with defaults filled in
+        def apply_defaults(value_object, fields)
+          value_object.attributes.each_with_object(fields) do |attribute, completed|
+            completed[attribute.name] = attribute.default unless completed.key?(attribute.name) || attribute.default.nil?
+          end
+        end
+
+        # The full door a value object's own fields pass through — shared by
+        # `build` and `normalize_composite_fields`, so a nested field refuses
+        # exactly like the same type declared directly on a command.
+        #
+        # @param value_object [Class] the `Bluebook::ValueObject` subclass to
+        #   validate `fields` against
+        # @param fields [Hash{Symbol => Object}] already-defaulted, nested-normalized fields
+        # @return [void]
+        # @raise [Runtime::UnknownArgument] if `fields` names an undeclared key
+        # @raise [Runtime::TypeMismatch] if a required field is missing or wrong-shaped
+        # @raise [Runtime::InvariantViolation] if `fields` breaks a declared invariant
+        def validate!(value_object, fields)
+          # C6.3 — a value object validates on construction from input only; state
+          # read back from the store is trusted as written, so tightening an
+          # invariant never makes an old record unreadable. `hydrate` sets this flag.
+          return if trusting_stored_state?
+
+          check_unknown_fields(value_object, fields)
+          check_required_fields(value_object, fields)
+          admit_member(value_object, fields)
+          check_admitted(value_object, fields)
+          check_list_shapes(value_object, fields)
+          check_numeric_fields(value_object, fields)
+          check_scalar_shapes(value_object, fields)
+          check_patterns(value_object, fields)
+          check_invariants(value_object, fields)
+        end
+
+        # Renders a value object's fields as a canonical JSON string, for an
+        # invariant refusal to quote.
+        #
+        # @param fields [Hash{Symbol, String => Object}] the field values to render
+        # @return [String] `fields`, sorted by key name and JSON-encoded
+        def canonical_fields(fields)
+          JSON.generate(fields.sort_by { |name, _| name.to_s }.to_h)
+        end
+
+        private
+
+        def normalize_composite_field(aggregate, attribute, fields)
+          # A list member hydrates the same as a top-level list, so a value
+          # read back from the store matches the shape a live dispatch wrote.
+          # Load door only — an input list member is left as offered.
+          return hydrate_stored_list(aggregate, attribute, fields) if attribute.list?
+
+          raw = fields[attribute.name]
+          return if raw.nil? || raw.is_a?(self)
+
+          nested = value_object_for(aggregate, attribute.type)
+          return unless nested
+
+          nested_fields = apply_defaults(nested, fields_for(nested, attribute.name, raw))
+          nested_fields = normalize_composite_fields(aggregate, nested, nested_fields)
+          validate!(nested, nested_fields)
+          fields[attribute.name] = nested_fields
+        end
+
+        def hydrate_stored_list(aggregate, attribute, fields)
+          return unless trusting_stored_state?
+
+          fields[attribute.name] = for_attribute(aggregate, attribute, fields[attribute.name])
+        end
+
+        def check_invariants(value_object, fields)
+          value_object.invariants.each do |invariant|
+            next if Bluebook::Expression::Evaluator.call_rule(invariant, fields)
+
+            raise InvariantViolation,
+                  RefusalWording.render_site("InvariantViolation", "value_object_invariant",
+                                             name: value_object.hecks_name, description: invariant.description,
+                                             offered: canonical_fields(fields))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/value.rb

@@ -3,6 +3,10 @@ require_relative "../rendering"
 require_relative "value/invariant_violation"
 require_relative "value/field_checks"
 require_relative "value/coercion"
+require_relative "value/references"
+require_relative "value/validation"
+require_relative "value/flags"
+require_relative "value/identifiers"
 require_relative "value/entity_list_coercion"
 require_relative "value/admission"
 
@@ -14,6 +18,10 @@ module Hecks
     class Value
       extend FieldChecks
       extend Coercion
+      extend References
+      extend Validation
+      extend Flags
+      extend Identifiers
       extend EntityListCoercion
       extend Admission
 
@@ -104,18 +112,22 @@ module Hecks
       #   more than one
       def self.materialize_unwrapped(value)
         case value
-        when self
-          sole = value.value_object.sole_attribute
-          return materialize_unwrapped(value[sole.name]) if sole
-
-          # Not `value.to_h`: it materializes nested values to Hashes, ending the recursion.
-          value.value_object.attributes.to_h { |attr| [attr.name, materialize_unwrapped(value[attr.name])] }
+        when self then unwrap_value_object(value)
         when Array then value.map { |item| materialize_unwrapped(item) }
         when Hash then value.transform_values { |item| materialize_unwrapped(item) }
         else value
         end
       end
 
+      def self.unwrap_value_object(value)
+        sole = value.value_object.sole_attribute
+        return materialize_unwrapped(value[sole.name]) if sole
+
+        # Not `value.to_h`: it materializes nested values to Hashes, ending the recursion.
+        value.value_object.attributes.to_h { |attr| [attr.name, materialize_unwrapped(value[attr.name])] }
+      end
+      private_class_method :unwrap_value_object
+
       # Reduces an append-only `list_of` sub-log to its current state: the latest row per `key`.
       # Grouping only; what counts as removed, and the ordering, belong to the caller.
       #

data/lib/hecks/rust_build/conformance/surface.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module RustBuild
+    module Conformance
+      # The comparable surface of a run: what Ruby and a Rust artifact must both reproduce, with
+      # what only one side carries stripped away.
+      module Surface
+        # The refusal kinds are not compared for ad-hoc filter steps: C8.3
+        # (docs/semantics/bluebook-semantics.md) is open (RuntimeError in Ruby, TypeMismatch in
+        # Rust), and only the message is byte-exact.
+        FILTER_VERB = "filter "
+
+        module_function
+
+        # @param result [Hash] `Fuzzing::Replay`'s answer
+        # @return [Hash{String => Object}] the surface a Rust artifact must reproduce
+        def comparable(result)
+          surface = {
+            "instances" => result[:instances].transform_values { |state| JSON.parse(JSON.generate(state)) },
+            "events"    => result[:events].map { |event| event_surface(event) },
+            "refusals"  => result[:refusals].map { |refusal| refusal_surface(refusal) }
+          }
+          dry_runs = dry_run_surface(result[:dry_runs])
+          surface["dry_runs"] = dry_runs unless dry_runs.empty?
+          surface
+        end
+
+        def refusal_surface(refusal)
+          { "verb" => refusal[:verb], "error" => refusal[:error], "kind" => refusal[:kind]&.split("::")&.last }
+        end
+
+        # `verb` and `ok` only, as `Hecks::Fuzzing::Differential` compares; omitted when none.
+        def dry_run_surface(dry_runs)
+          dry_runs.map { |dry| { "verb" => dry[:verb].to_s, "ok" => dry[:ok] } }
+        end
+
+        def event_surface(event)
+          { "name" => event[:name], "aggregate" => event[:aggregate], "id" => event[:id].to_s,
+            "payload" => JSON.parse(JSON.generate(event[:payload])) }
+        end
+
+        # Strips what a Rust run carries that Ruby has no analog for: `emitted_*` snapshot flags
+        # (ADR 0048) and the wall-clock `occurred_at` stamp two runs can never match.
+        def normalize(theirs)
+          strip_snapshot_flags(theirs["instances"])
+          strip_timestamps(theirs["events"])
+          theirs
+        end
+
+        def strip_snapshot_flags(instances)
+          return unless instances.is_a?(Hash)
+
+          instances.each_value do |record|
+            record.reject! { |key, _| key.start_with?("emitted_") } if record.is_a?(Hash)
+          end
+        end
+
+        def strip_timestamps(events)
+          return unless events.is_a?(Array)
+
+          events.each { |event| event.delete("occurred_at") if event.is_a?(Hash) }
+        end
+
+        def drop_filter_kinds(side)
+          return unless side["refusals"].is_a?(Array)
+
+          side["refusals"].each { |r| r.delete("kind") if r.is_a?(Hash) && r["verb"].to_s.start_with?(FILTER_VERB) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/conformance.rb

@@ -4,6 +4,7 @@ require "json"
 require "open3"
 require_relative "../rust_build"
 require_relative "native_build"
+require_relative "conformance/surface"
 
 module Hecks
   module RustBuild
@@ -19,11 +20,6 @@ module Hecks
       USAGE = "usage: hecks check_conformance <domain> <script.json> " \
               "[rust_output.json | native | build | path/to/binary | path/to/module.wasm]"
 
-      # The refusal kinds are not compared for ad-hoc filter steps: C8.3
-      # (docs/semantics/bluebook-semantics.md) is open (RuntimeError in Ruby, TypeMismatch in
-      # Rust), and only the message is byte-exact.
-      FILTER_VERB = "filter "
-
       module_function
 
       # @param argv [Array<String>] the domain, the script and optionally the artifact
@@ -35,10 +31,10 @@ module Hecks
         domain, script, other = argv
         raise Failure, USAGE unless domain && script
 
-        ours = comparable(Hecks::Fuzzing::Replay.call(domain, JSON.parse(File.read(script)).fetch("steps")))
+        ours = Surface.comparable(Hecks::Fuzzing::Replay.call(domain, JSON.parse(File.read(script)).fetch("steps")))
         return print_result(ours) unless other
 
-        theirs = normalize(JSON.parse(artifact_output(domain, script, other)))
+        theirs = Surface.normalize(JSON.parse(artifact_output(domain, script, other)))
         report(domain, script, ours, theirs)
       end
 
@@ -47,48 +43,33 @@ module Hecks
         0
       end
 
-      # @param result [Hash] `Fuzzing::Replay`'s answer
-      # @return [Hash{String => Object}] the surface a Rust artifact must reproduce
-      def comparable(result)
-        surface = {
-          "instances" => result[:instances].transform_values { |state| JSON.parse(JSON.generate(state)) },
-          "events"    => result[:events].map { |event| event_surface(event) },
-          "refusals"  => result[:refusals].map do |refusal|
-            { "verb" => refusal[:verb], "error" => refusal[:error], "kind" => refusal[:kind]&.split("::")&.last }
-          end
-        }
-        # `verb` and `ok` only, as `Hecks::Fuzzing::Differential` compares; omitted when none.
-        dry_runs = result[:dry_runs].map { |dry| { "verb" => dry[:verb].to_s, "ok" => dry[:ok] } }
-        surface["dry_runs"] = dry_runs unless dry_runs.empty?
-        surface
-      end
-
-      def event_surface(event)
-        { "name" => event[:name], "aggregate" => event[:aggregate], "id" => event[:id].to_s,
-          "payload" => JSON.parse(JSON.generate(event[:payload])) }
-      end
-
       # The artifact's JSON for the script: live from a binary, or read from a file.
       def artifact_output(domain, script, other)
         case other
         when "native" then run_binary(native_binary || missing_native!, script)
         when "build" then run_binary(built_binary(domain), script)
-        when /\.wasm\z/
-          raise Failure, "#{other}: no such file — run hecks build_wasm #{domain} first" unless File.exist?(other)
-
-          run_process(["wasmtime", "run", other], File.read(script))
-        when ->(path) { !path.end_with?(".json") && File.file?(path) && File.executable?(path) }
-          # A pinned per-domain binary, as named by a sweep's `replay:` line.
-          run_binary(other, script)
+        when /\.wasm\z/ then run_wasm(domain, script, other)
+        when method(:pinned_binary?) then run_binary(other, script)
         else File.read(other)
         end
       end
 
+      def run_wasm(domain, script, wasm)
+        raise Failure, "#{wasm}: no such file — run hecks build_wasm #{domain} first" unless File.exist?(wasm)
+
+        run_process(["wasmtime", "run", wasm], File.read(script))
+      end
+
+      # A pinned per-domain binary, as named by a sweep's `replay:` line.
+      def pinned_binary?(path)
+        !path.end_with?(".json") && File.file?(path) && File.executable?(path)
+      end
+
       def run_binary(binary, script) = run_process([binary], File.read(script))
 
       def run_process(command, stdin_data)
         stdout, status = Open3.capture2(*command, stdin_data: stdin_data)
-        raise Failure, "#{command.join(' ')} exited #{status.exitstatus}:\n#{stdout}" unless status.success?
+        raise Failure, "#{command.join(" ")} exited #{status.exitstatus}:\n#{stdout}" unless status.success?
 
         stdout
       end
@@ -111,20 +92,8 @@ module Hecks
           raise Failure, "no `#{feature}` feature in rust/Cargo.toml — run hecks project_rust #{domain} first"
       end
 
-      # Strips what a Rust run carries that Ruby has no analog for: `emitted_*` snapshot flags
-      # (ADR 0048) and the wall-clock `occurred_at` stamp two runs can never match.
-      def normalize(theirs)
-        if theirs["instances"].is_a?(Hash)
-          theirs["instances"].each_value do |record|
-            record.reject! { |key, _| key.start_with?("emitted_") } if record.is_a?(Hash)
-          end
-        end
-        theirs["events"].each { |event| event.delete("occurred_at") if event.is_a?(Hash) } if theirs["events"].is_a?(Array)
-        theirs
-      end
-
       def report(domain, script, ours, theirs)
-        [ours, theirs].each { |side| drop_filter_kinds(side) }
+        [ours, theirs].each { |side| Surface.drop_filter_kinds(side) }
         mismatches = mismatches(ours, theirs)
         if mismatches.empty?
           puts "#{domain} / #{script}: matches."
@@ -135,24 +104,23 @@ module Hecks
         1
       end
 
-      def drop_filter_kinds(side)
-        return unless side["refusals"].is_a?(Array)
-
-        side["refusals"].each { |r| r.delete("kind") if r.is_a?(Hash) && r["verb"].to_s.start_with?(FILTER_VERB) }
-      end
-
       def mismatches(ours, theirs)
         found = %w[instances events refusals].filter_map do |key|
           next if ours[key] == theirs[key]
 
           "#{key}:\n  ruby:  #{ours[key].inspect}\n  other: #{theirs[key].inspect}"
         end
-        their_dry_runs = Array(theirs["dry_runs"]).map { |dry| dry.slice("verb", "ok") }
-        if (ours["dry_runs"] || []) != their_dry_runs
-          found << "dry_runs:\n  ruby:  #{ours['dry_runs'].inspect}\n  other: #{their_dry_runs.inspect}"
-        end
+        dry = dry_run_mismatch(ours, theirs)
+        found << dry if dry
         found
       end
+
+      def dry_run_mismatch(ours, theirs)
+        their_dry_runs = Array(theirs["dry_runs"]).map { |dry| dry.slice("verb", "ok") }
+        return if (ours["dry_runs"] || []) == their_dry_runs
+
+        "dry_runs:\n  ruby:  #{ours["dry_runs"].inspect}\n  other: #{their_dry_runs.inspect}"
+      end
     end
   end
 end

data/lib/hecks/rust_build/conformance_fuzz.rb

@@ -22,6 +22,9 @@ module Hecks
       # What a domain directory's basename may be: a plain identifier, never `.` or `..`.
       DOMAIN_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
 
+      # One fuzz run: what is replayed, against which artifact, how much, and where the scripts go.
+      Run = Struct.new(:domain, :artifact, :seeds, :steps, :scratch)
+
       module_function
 
       # @param argv [Array<String>] the domain, the artifact, and optionally seeds and steps
@@ -30,16 +33,20 @@ module Hecks
       def call(argv)
         require_relative "../../hecks"
         require_relative "../fuzzing"
+        run = build_run(argv)
+        (1..run.seeds).each { |seed| replay(run, seed) }
+        FileUtils.rm_rf(run.scratch)
+        puts "#{run.domain}: #{run.seeds} generated sequence(s) x #{run.steps} step(s) each, " \
+             "all matched #{run.artifact}."
+        0
+      end
+
+      def build_run(argv)
         domain, artifact, seeds, steps = argv
         raise Failure, USAGE unless domain && artifact
 
-        seeds = Integer(seeds || ENV["SEEDS"] || 10)
-        steps = Integer(steps || ENV["STEPS"] || 25)
-        scratch = scratch_dir(domain)
-        (1..seeds).each { |seed| replay(domain, artifact, seed, seeds, steps, scratch) }
-        FileUtils.rm_rf(scratch)
-        puts "#{domain}: #{seeds} generated sequence(s) x #{steps} step(s) each, all matched #{artifact}."
-        0
+        Run.new(domain, artifact, Integer(seeds || ENV["SEEDS"] || 10), Integer(steps || ENV["STEPS"] || 25),
+                scratch_dir(domain))
       end
 
       # A fresh directory per run, under the cache root outside the gem, so concurrent runs never
@@ -57,15 +64,19 @@ module Hecks
         Dir.mktmpdir("#{name}-", parent)
       end
 
-      def replay(domain, artifact, seed, seeds, steps, scratch)
-        sequence = Hecks::Fuzzing::SequenceGenerator.generate(domain, seed: seed, steps: steps)
-        path = File.join(scratch, "seed-#{seed}.json")
-        File.write(path, KernelInput.json(domain, sequence))
-        return if Conformance.call([domain, path, artifact]).zero?
+      def replay(run, seed)
+        sequence = Hecks::Fuzzing::SequenceGenerator.generate(run.domain, seed: seed, steps: run.steps)
+        path = File.join(run.scratch, "seed-#{seed}.json")
+        File.write(path, KernelInput.json(run.domain, sequence))
+        return if Conformance.call([run.domain, path, run.artifact]).zero?
+
+        raise Failure, divergence_message(run, seed, path)
+      end
 
-        raise Failure, "hecks fuzz_conformance: seed #{seed}/#{seeds} diverged against #{artifact} " \
-                       "(see the conformance output above) — " \
-                       "reproduce with: hecks check_conformance #{domain} #{path} #{artifact}"
+      def divergence_message(run, seed, path)
+        "hecks fuzz_conformance: seed #{seed}/#{run.seeds} diverged against #{run.artifact} " \
+          "(see the conformance output above) — " \
+          "reproduce with: hecks check_conformance #{run.domain} #{path} #{run.artifact}"
       end
     end
   end

data/lib/hecks/rust_build/coverage.rb

@@ -5,6 +5,8 @@ require "json"
 require "open3"
 require "tmpdir"
 require_relative "../rust_build"
+require_relative "coverage_parts/expected"
+require_relative "coverage_parts/printer"
 
 module Hecks
   module RustBuild
@@ -47,61 +49,22 @@ module Hecks
 
       def generated_root = File.join(rust_dir, "src/generated")
 
-      # Entity-scoped query ids at any depth (`Domain::Aggregate.Entity.Query`); mirrors the
-      # generator's own entity query entries.
-      def entity_query_ids(owner_id, entities)
-        entities.flat_map do |entity|
-          entity_id = "#{owner_id}.#{entity.fetch(:name)}"
-          entity.fetch(:queries, []).map { |q| "#{entity_id}.#{q.fetch(:name)}" } +
-            entity_query_ids(entity_id, entity.fetch(:entities, []))
-        end
-      end
-
-      # The [kind, id] pairs the IR implies, independent of the manifest.
-      def expected_from_ir(payload)
-        domain_name = payload.fetch(:name)
-        expected = payload.fetch(:aggregates).flat_map { |aggregate| aggregate_constructs(domain_name, aggregate) }
-        payload.fetch(:read_models).each { |rm| expected << [:read_model, "#{domain_name}::#{rm.fetch(:name)}"] }
-        payload.fetch(:policies).each { |p| expected << [:policy, "#{domain_name}::#{p.fetch(:name)}"] }
-        payload.fetch(:process_managers).each { |pm| expected << [:process_manager, "#{domain_name}::#{pm.fetch(:name)}"] }
-        # An `ir.json` from before the `lineage` key existed has none: nothing to expect.
-        payload.fetch(:lineage, {}).fetch(:capable_aggregates, []).each do |aggregate|
-          expected << [:lineage_aggregate, "#{domain_name}::#{aggregate.fetch(:name)}"]
-        end
-        expected
-      end
-
-      def aggregate_constructs(domain_name, aggregate)
-        id = "#{domain_name}::#{aggregate.fetch(:name)}"
-        found = [[:aggregate, id]]
-        aggregate.fetch(:commands).each { |c| found << [:command, "#{id}.#{c.fetch(:name)}"] }
-        aggregate.fetch(:queries).each { |q| found << [:query, "#{id}.#{q.fetch(:name)}"] }
-        entity_query_ids(id, aggregate.fetch(:entities)).each { |query_id| found << [:query, query_id] }
-        aggregate.fetch(:entities).each do |entity|
-          entity_id = "#{id}.#{entity.fetch(:name)}"
-          found << [:entity, entity_id]
-          entity.fetch(:commands).each { |c| found << [:entity_command, "#{entity_id}.#{c.fetch(:name)}"] }
-        end
-        aggregate.fetch(:ports).each do |port|
-          port.fetch(:operations).each { |op| found << [:port_operation, "#{id}.#{port.fetch(:name)}.#{op.fetch(:name)}"] }
-        end
-        found
-      end
-
       # Parses a generated module's `ir.json` and `manifest.json`, adding a synthetic `unaccounted`
       # finding for any IR construct the manifest omits.
       def coverage_findings(mod_dir)
-        ir_path = File.join(mod_dir, "ir.json")
-        File.exist?(ir_path) or raise Failure, "#{ir_path}: missing — this generated tree predates ir.json " \
-                                               "(hecks project_rust writes it now); re-run hecks project_rust for this domain"
-        ir = JSON.parse(File.read(ir_path), symbolize_names: true)
-        manifest_path = File.join(mod_dir, "manifest.json")
-        File.exist?(manifest_path) or raise Failure, "#{manifest_path}: missing — re-run hecks project_rust for this " \
-                                                     "domain to write it"
-        manifest = JSON.parse(File.read(manifest_path), symbolize_names: true)
+        ir = read_json(File.join(mod_dir, "ir.json"),
+                       "this generated tree predates ir.json (hecks project_rust writes it now); " \
+                       "re-run hecks project_rust for this domain")
+        manifest = read_json(File.join(mod_dir, "manifest.json"),
+                             "re-run hecks project_rust for this domain to write it")
         [ir, manifest + unaccounted_findings(ir, manifest)]
       end
 
+      def read_json(path, hint)
+        File.exist?(path) or raise Failure, "#{path}: missing — #{hint}"
+        JSON.parse(File.read(path), symbolize_names: true)
+      end
+
       def allowlist_rule_matches?(rule, finding)
         rule[:kind] == finding[:kind].to_s &&
           rule[:gap_class] == finding[:gap_class].to_s &&
@@ -113,13 +76,15 @@ module Hecks
       # A synthetic finding for each expected construct with no manifest entry at all: a gap in
       # the manifest writer itself.
       def unaccounted_findings(payload, manifest)
-        ids = Hash.new { |hash, kind| hash[kind] = Set.new }
-        manifest.each { |entry| ids[entry[:kind].to_sym] << entry[:id] }
-        expected_from_ir(payload).reject { |kind, id| ids[kind].include?(id) }.map do |kind, id|
-          { kind: kind.to_s, id: id, generated: false, gap_class: "unaccounted", construct: "unaccounted",
-            reason: "expected per ir.json, but manifest.json has NO entry for it at all — not even a " \
-                    "recorded skip; the generator's own accounting missed this construct entirely" }
-        end
+        ids = manifest.group_by { |entry| entry[:kind].to_sym }.transform_values { |entries| entries.to_set { |e| e[:id] } }
+        Expected.from_ir(payload).reject { |kind, id| ids.fetch(kind, Set.new).include?(id) }
+                .map { |kind, id| unaccounted(kind, id) }
+      end
+
+      def unaccounted(kind, id)
+        { kind: kind.to_s, id: id, generated: false, gap_class: "unaccounted", construct: "unaccounted",
+          reason: "expected per ir.json, but manifest.json has NO entry for it at all — not even a " \
+                  "recorded skip; the generator's own accounting missed this construct entirely" }
       end
 
       # A real functional gap: not generated, or generated but unrouted.
@@ -127,14 +92,17 @@ module Hecks
 
       # Every rule must still excuse a real gap somewhere under `src/generated/`.
       def check_allowlist
-        gaps = Dir.glob(File.join(generated_root, "*/ir.json")).flat_map do |ir_path|
-          coverage_findings(File.dirname(ir_path))[1].select { |finding| functional_gap?(finding) }
-        end
+        gaps = Dir.glob(File.join(generated_root, "*/ir.json")).flat_map { |ir_path| gaps_in(File.dirname(ir_path)) }
         stale = ALLOWLIST.reject { |rule| gaps.any? { |finding| allowlist_rule_matches?(rule, finding) } }
-        if stale.empty?
-          puts "hecks rust_coverage --check-allowlist: all #{ALLOWLIST.size} rules still excuse a real gap"
-          return 0
-        end
+        return report_stale(stale) unless stale.empty?
+
+        puts "hecks rust_coverage --check-allowlist: all #{ALLOWLIST.size} rules still excuse a real gap"
+        0
+      end
+
+      def gaps_in(mod_dir) = coverage_findings(mod_dir)[1].select { |finding| functional_gap?(finding) }
+
+      def report_stale(stale)
         stale.each do |rule|
           warn "STALE ALLOWLIST RULE: #{rule.slice(:kind, :gap_class, :construct)} matches no gap in any generated " \
                "module — the gap it excused is gone; delete the rule"
@@ -171,48 +139,8 @@ module Hecks
 
       def print_report(domain, mod_dir)
         ir, findings = coverage_findings(mod_dir)
-        # A construct is implemented only when generated and routed (where routing applies): a
-        # `dispatch_*` that compiles but nothing can call is not working.
-        implemented, remainder = findings.partition { |f| f[:generated] && f[:routed] != false }
-        deferred, gap = remainder.partition { |f| allowlisted(f) }
-        puts "=" * 72
-        puts "hecks rust_coverage #{domain}  (source: manifest.json)"
-        puts "=" * 72
-        puts "#{ir.fetch(:name)} — #{findings.size} constructs accounted for " \
-             "(#{implemented.size} implemented, #{deferred.size} deferred, #{gap.size} GAP)"
-        print_bucket("IMPLEMENTED", implemented) unless implemented.empty?
-        print_deferred(deferred)
-        print_gaps(gap)
-        puts
-        gap.empty? ? 0 : 1
-      end
-
-      def print_bucket(label, entries)
-        puts "\n#{label} (#{entries.size})"
-        sorted(entries).each { |entry| print_entry(entry) }
+        Printer.report(domain, ir.fetch(:name), findings, method(:allowlisted))
       end
-
-      def print_deferred(deferred)
-        puts "\nDEFERRED (#{deferred.size}) — on the allowlist, with its cited reason"
-        sorted(deferred).each do |entry|
-          puts "  [#{entry[:kind]}] #{entry[:id]}"
-          puts "      allowlist: #{allowlisted(entry)[:doc]}"
-        end
-      end
-
-      def print_gaps(gap)
-        puts "\nGAP (#{gap.size}) — missing, and NOT on the allowlist: a real, actionable finding"
-        sorted(gap).each { |entry| print_entry(entry) }
-      end
-
-      def print_entry(entry)
-        line = "  [#{entry[:kind]}] #{entry[:id]}"
-        line += " (#{entry[:gap_class]})" if entry[:gap_class]
-        puts line
-        puts "      #{entry[:reason]}" if entry[:reason]
-      end
-
-      def sorted(entries) = entries.sort_by { |entry| [entry[:kind].to_s, entry[:id]] }
     end
   end
 end