hecks 1.3.0 → 1.5.0

data/lib/hecks/fuzzing/rotation_priority.rb

@@ -1,51 +1,61 @@
 module Hecks
   module Fuzzing
-    # THE WEIGHTED HALF OF `QualityControl::Target.Rotation`
+    # The weighted half of `QualityControl::Target.Rotation`
     # (qa/bluebook/quality_control.bluebook) — see that query's own
     # comment for why the ledger itself still only offers
     # least-recently-swept order: `order_by` sorts by exactly one stored
     # field, and a target's actual rotation priority wants two blended
-    # together (time since last swept, AND recent yield), which nothing
+    # together (time since last swept, and recent yield), which nothing
     # in the query sublanguage can express. `Rotation` stays the raw
     # view; this module is where the blend actually happens, against the
     # rows that query already returns.
     #
-    # PURE, DELIBERATELY. Every method here is a function of its own
-    # arguments only — no clock read, no query dispatched, nothing
-    # random — so this is unit-testable with plain hashes and no ledger
-    # boot at all, and reruns identically given the same rotation, the
-    # same `now` and the same dials. `now` arrives as an argument for
-    # the exact reason `Target.Claim`'s own comment already gives: a
-    # pure function cannot ask the time, so whoever calls this supplies
-    # it, exactly as it supplies an id.
+    # ## Pure, deliberately
     #
-    # WHERE THIS ACTUALLY MATTERS, AND WHERE IT DOES NOT — checked
-    # against `bin/qa_sweep`'s own code, not assumed. `bin/qa_sweep
-    # --all` sweeps every currently-waiting target in one pass,
-    # regardless of order (`run_all_mode`'s own `waiting.map { spawn_
-    # sweep_child }` — every element the query returned, never
-    # `.first`), so nothing about this module's own ordering changes
-    # what `--all` does; it already sweeps everything the ledger has to
-    # offer. What it changes is `bin/qa_sweep` invoked with NO target
-    # argument, which today picks exactly one target via `Target.
-    # Rotation.first` — wiring `.pick` in there instead is this module's
-    # one real caller, and (per the same investigation) its only one:
-    # there is no separate scheduling or concurrency-limit mechanism
-    # elsewhere in this repository for it to feed instead.
+    # Every method here is a function of its own arguments only — no clock
+    # read, no query dispatched, nothing random — so this is unit-testable
+    # with plain hashes and no ledger boot at all, and reruns identically
+    # given the same rotation, the same `now` and the same dials. `now`
+    # arrives as an argument for the exact reason `Target.Claim`'s own
+    # comment already gives: a pure function cannot ask the time, so
+    # whoever calls this supplies it, exactly as it supplies an id.
+    #
+    # ## Where this actually matters, and where it does not
+    #
+    # Checked against `bin/qa_sweep`'s own code, not assumed. `bin/qa_sweep
+    # --all` sweeps every currently-waiting target in one pass, regardless
+    # of order (`run_all_mode`'s own `waiting.map { spawn_sweep_child }` —
+    # every element the query returned, never `.first`), so nothing about
+    # this module's own ordering changes what `--all` does; it already
+    # sweeps everything the ledger has to offer. What it changes is
+    # `bin/qa_sweep` invoked with no target argument, which today picks
+    # exactly one target via `Target.Rotation.first` — wiring `.pick` in
+    # there instead is this module's one real caller, and (per the same
+    # investigation) its only one: there is no separate scheduling or
+    # concurrency-limit mechanism elsewhere in this repository for it to
+    # feed instead.
     module RotationPriority
       module_function
 
-      # THE NEXT STORED `Target.yield_score` — decay what survives from
+      # The next stored `Target.yield_score` — decay what survives from
       # before, then add whatever this just-concluded period actually
       # found. Integer division, like every other count in this ledger
       # (`Sweep.CheckCount`, `Bug.BugOrder`): a yield score is a
       # priority signal, not a precise statistic, and a fractional score
       # would need a value object this ledger does not have.
       #
-      # `decay_percent` DEFAULTS TO THE DIAL, NOT A LITERAL, so a caller
+      # `decay_percent` defaults to the dial, not a literal, so a caller
       # that does not care still gets the practice's own current answer
       # to "how much of this is 'recent'" rather than a second, silently
       # drifting copy of the same number.
+      #
+      # @param old_score [Integer] the target's `Target.yield_score` before this period
+      # @param surprises_this_period [Integer] how many Surprised checks this period found
+      # @param decay_percent [Integer] percent of `old_score` that survives into the new
+      #   score; defaults to `QualityControlDials::YIELD_DECAY_PERCENT`
+      # @return [Integer] the next `Target.yield_score` to store
+      # @raise [ArgumentError] if `old_score` is negative
+      # @raise [ArgumentError] if `surprises_this_period` is negative
       def next_yield_score(old_score:, surprises_this_period:,
                            decay_percent: QualityControlDials::YIELD_DECAY_PERCENT)
         raise ArgumentError, "old_score must not be negative" if old_score.negative?
@@ -54,14 +64,14 @@ module Hecks
         ((old_score * decay_percent) / 100) + surprises_this_period
       end
 
-      # THE PICK ITSELF. `rows` is whatever `Target.Rotation` returned —
+      # The pick itself. `rows` is whatever `Target.Rotation` returned —
       # each row a hash carrying at least `:last_swept` and
       # `:yield_score`, both `{ value: Integer }`, the shape every
       # VO-typed field in this ledger already comes back as. Returns
       # `nil` for an empty rotation, the same "nothing waiting" case
       # `bin/qa_sweep` already handles by seeding the default targets.
       #
-      # THE FLOOR WINS OUTRIGHT — no starvation, on purpose (see
+      # The floor wins outright — no starvation, on purpose (see
       # `QualityControlDials::ROTATION_STALE_FLOOR_SECONDS`'s own
       # comment for why a floor and not a total exclusion). A row stale
       # past `floor_seconds` is picked ahead of every row that is not,
@@ -70,13 +80,23 @@ module Hecks
       # keeps the floor from becoming a new source of starvation between
       # two long-neglected targets.
       #
-      # BELOW THE FLOOR, HIGHEST COMBINED SCORE WINS. `staleness +
+      # Below the floor, highest combined score wins. `staleness +
       # (yield_score * weight_seconds)` — plain addition, never a ratio
       # or anything that could divide by zero, and the units are
       # deliberately the same (seconds) so `weight_seconds` reads as
       # "how many seconds of extra staleness one point of yield is
       # worth" rather than an opaque multiplier nobody could sanity
       # check by eye.
+      #
+      # @param rows [Array<Hash>] rows from `Target.Rotation`, each carrying at least
+      #   `:last_swept` and `:yield_score` as `{ value: Integer }`
+      # @param now [Integer] the current time, Unix epoch seconds
+      # @param weight_seconds [Integer] seconds of extra staleness one point of yield is
+      #   worth; defaults to `QualityControlDials::YIELD_WEIGHT_SECONDS`
+      # @param floor_seconds [Integer] staleness, in seconds, past which a row is picked
+      #   ahead of every row not yet that stale; defaults to
+      #   `QualityControlDials::ROTATION_STALE_FLOOR_SECONDS`
+      # @return [Hash, nil] the picked row, or `nil` if `rows` is empty
       def pick(rows, now:, weight_seconds: QualityControlDials::YIELD_WEIGHT_SECONDS,
                floor_seconds: QualityControlDials::ROTATION_STALE_FLOOR_SECONDS)
         return nil if rows.empty?

data/lib/hecks/fuzzing/rust_gap_manifest.rb

@@ -0,0 +1,139 @@
+require "json"
+require "hecks/naming"
+
+module Hecks
+  module Fuzzing
+    # What a compiled Rust binary declares it did not generate — read off the
+    # `manifest.json` files `rust/project/domain_generator.rb` writes beside
+    # every generated module, never inferred from Rust's refusal wording.
+    #
+    # The differential fuzzer (`Differential.diff`) drops a query or
+    # read-model verb from the comparison if and only if the generator's own
+    # manifest recorded it as `generated: false`, with the `gap_class` and
+    # `construct` that explain why — never by pattern-matching Rust's
+    # refusal wording ("is not generated for this domain"), which would
+    # tolerate whatever Rust happened to say, including a codegen
+    # regression that silently started refusing a construct it once
+    # generated. A refusal the manifest does not account for stays in the
+    # comparison and fails it.
+    #
+    # ## Which manifests describe a binary
+    #
+    # `build_and_pin` (spec/support/rust_conformance_helpers.rb) and
+    # `bin/qa_generated_domains` both pin a feature's binary at
+    # `<rust_dir>/target/debug/rust-<feature>`. That binary compiles
+    # `src/generated/<feature>/` plus every shared framework chapter (a
+    # generated directory with no `merged.rs` of its own — `governance`,
+    # `identity`; see the generated `mod.rs` header). Ids in those manifests
+    # are domain-qualified, so a chapter a domain never attaches contributes
+    # entries no sequence for that domain can name.
+    #
+    # ## A missing manifest tolerates nothing
+    #
+    # A hand-written fixture crate, or a tree generated before manifests
+    # existed, has no declaration to honour, so every refusal it produces
+    # is compared as-is. That is the fail-closed direction.
+    class RustGapManifest
+      # The only kinds the kernel answers as a query step. A not-generated
+      # command changes state, so dropping its refusal would not make the
+      # comparison honest; those stay compared and fail.
+      TOLERABLE_KINDS = %w[query read_model].freeze
+      PINNED_BINARY = %r{\A(?<rust_dir>.+)/target/debug/rust-(?<feature>[a-z0-9_]+)\z}
+
+      attr_reader :rust_dir, :feature, :entries
+
+      # Builds the manifest reader for the pinned conformance binary at `binary`.
+      #
+      # @param binary [String] path to a pinned binary, `<rust_dir>/target/debug/rust-<feature>`
+      # @return [Fuzzing::RustGapManifest] the manifest reader for that binary's feature
+      # @raise [ArgumentError] if `binary` does not match the pinned-binary path shape
+      def self.for_binary(binary)
+        match = PINNED_BINARY.match(File.expand_path(binary.to_s))
+        unless match
+          raise ArgumentError, "#{binary.inspect} is not a pinned conformance binary " \
+                               "(<rust_dir>/target/debug/rust-<feature>) — cannot tell which manifest describes it"
+        end
+
+        new(rust_dir: match[:rust_dir], feature: match[:feature])
+      end
+
+      # Every committed manifest entry under `rust_dir`, each tagged with the
+      # generated module it came from — what the boundary ratchet and
+      # bin/rust_coverage's allowlist staleness check read.
+      #
+      # @param rust_dir [String] path to the Rust project root (holds `src/generated/*/`)
+      # @return [Array<Hash>] every `src/generated/*/manifest.json` entry, each a
+      #   String-keyed manifest Hash plus `"module" => String` naming the directory it came from
+      def self.all_entries(rust_dir)
+        Dir.glob(File.join(rust_dir, "src/generated/*/manifest.json")).flat_map do |path|
+          module_name = File.basename(File.dirname(path))
+          JSON.parse(File.read(path)).map { |entry| entry.merge("module" => module_name) }
+        end
+      end
+
+      # @param rust_dir [String] path to the Rust project root (holds `src/generated/*/`)
+      # @param feature [String] the domain feature this manifest reader describes
+      def initialize(rust_dir:, feature:)
+        @rust_dir = rust_dir
+        @feature  = feature
+        @entries  = manifest_paths.flat_map { |path| JSON.parse(File.read(path)) }.freeze
+        @not_generated = index_not_generated
+      end
+
+      # The manifest entry that declares `verb` not generated, or nil. `verb`
+      # is the wire spelling a sequence step uses; an ad hoc filter (a Hash)
+      # is never declared and answers nil.
+      #
+      # @param verb [String, Object] the wire-spelled query or read-model verb to look up
+      # @return [Hash, nil] the String-keyed manifest entry declaring `verb` not generated,
+      #   or nil if `verb` is not a String or no entry declares it
+      def not_generated(verb)
+        return nil unless verb.is_a?(String)
+
+        @not_generated[verb]
+      end
+
+      # Answers whether `verb` is declared not generated by this manifest.
+      #
+      # @param verb [String, Object] the wire-spelled query or read-model verb to look up
+      # @return [Boolean] whether the manifest declares `verb` not generated
+      def not_generated?(verb) = !not_generated(verb).nil?
+
+      # Lists every verb this manifest declares not generated.
+      #
+      # @return [Set<String>] every verb the manifest declares not generated
+      def not_generated_verbs = @not_generated.keys.to_set
+
+      private
+
+      def manifest_paths
+        generated = File.join(rust_dir, "src/generated")
+        own = File.join(generated, feature, "manifest.json")
+        chapters = Dir.glob(File.join(generated, "*/manifest.json")).reject do |path|
+          dir = File.dirname(path)
+          File.basename(dir) == feature || File.exist?(File.join(dir, "merged.rs"))
+        end
+        ([own] + chapters.sort).select { |path| File.exist?(path) }
+      end
+
+      def index_not_generated
+        @entries.each_with_object({}) do |entry, index|
+          next unless TOLERABLE_KINDS.include?(entry["kind"]) && entry["generated"] == false
+
+          wire_verbs(entry).each { |verb| index[verb] = entry }
+        end.freeze
+      end
+
+      # A query is asked by its id. A read model's id is "Domain::Name", but
+      # it is asked as "Domain.Name" or "Domain.name_in_snake_case" — the two
+      # spellings `kernel::read_model::find` accepts (`matches_snake_alias`,
+      # a port of `Hecks::Naming.snake`).
+      def wire_verbs(entry)
+        return [entry["id"]] if entry["kind"] == "query"
+
+        domain, name = entry["id"].split("::", 2)
+        ["#{domain}.#{name}", "#{domain}.#{Hecks::Naming.snake(name)}"].uniq
+      end
+    end
+  end
+end