hecks 1.3.0 → 1.4.0

data/lib/hecks/fuzzing/era_boundary.rb

@@ -2,20 +2,20 @@ require "hecks/ports/persistence/plugins/era"
 
 module Hecks
   module Fuzzing
-    # THE FORK-LOSS CLASS, AS A CHECK — not a fuzz. Every other mode in
-    # this file generates a sequence and compares two answers to the SAME
+    # **The fork-loss class, as a check** — not a fuzz. Every other mode in
+    # this file generates a sequence and compares two answers to the same
     # question; this one asks a single, unconditional question of a
-    # target's own REAL, already-configured `PostgresEra` ledger:
+    # target's own real, already-configured `PostgresEra` ledger:
     # does any ancestor era still hold writes nobody has merged forward?
     #
-    # THE BUG THIS TARGETS, NAMED EXACTLY. Minting a new era (an attribute
+    # **The bug this targets, named exactly**. Minting a new era (an attribute
     # or aggregate addition — `StorageShape.project`, lib/hecks/ports/
     # persistence/plugins/era/storage_shape.rb) advances the readable head
-    # to a NEW partition; an OLD checkout, or a process that boots slower
+    # to a new partition; an old checkout, or a process that boots slower
     # than the mint, can keep writing into the era it still believes is
     # current. Those writes are not lost — `Lineage#diverged_count`
     # (postgres_era/lineage/tail_merge.rb) can always find them — but
-    # nothing EVER asked it automatically. The practice's own ledger found
+    # nothing ever asked it automatically. The practice's own ledger found
     # exactly this live, twice: once as an operational gap this session's
     # Step 0 recovered by hand (`bin/merge_tail`, three conflicting
     # records, three eras deep), and once as BUG#24 (a superuser
@@ -26,15 +26,15 @@ module Hecks
     # line already answers by hand, run as an ordinary sweep Check instead
     # of only when a human remembers to ask.
     #
-    # THE TARGET'S REAL DATABASE, READ-ONLY, NEVER A DISPOSABLE ONE — every
+    # The target's real database, read-only, never a disposable one — every
     # other Postgres-touching mode here (`persistence_parity`,
     # `adapter_parity_sqlite`) owns a throwaway schema for the exact
     # reason it must never look at what a real deployment actually holds;
-    # this check exists FOR what a real deployment actually holds, so it
+    # this check exists for what a real deployment actually holds, so it
     # connects the same way `bin/merge_tail` itself does — the target's
     # own `.world` binding — and never writes anything: `eras`/
     # `diverged_count` are both plain `SELECT`s, and `ensure_base!` only
-    # ever provisions (`CREATE TABLE IF NOT EXISTS`) when THIS connection
+    # ever provisions (`CREATE TABLE IF NOT EXISTS`) when this connection
     # is the database's own provisioning owner, the identical idempotent
     # call every ordinary boot already makes. A target with no real,
     # reachable database configured (nothing provisioned locally, say) is
@@ -45,20 +45,30 @@ module Hecks
       module_function
 
       # `{ checked: true, diverged_total:, breakdown: [{ordinal:, diverged:}] }`
-      # or `{ checked: false, reason: "..." }` — the caller decides what a
-      # `false` means (an operational note, not a finding); a `true` with
+      # or `{ checked: false, kind:, reason: "..." }`. A `true` with
       # `diverged_total.positive?` is the finding this module exists to
       # surface: real post-cut writes an ancestor era is still holding.
+      #
+      # `kind:` splits the two things `checked: false` used to mean. Both
+      # answered the same shape, and `bin/qa_sweep` logged that shape as a
+      # held Check either way — so a refused connection or a `Lineage`
+      # defect read, in the ledger, exactly like an audit that ran and
+      # found nothing: counted toward `sweep.made` and the target's clean
+      # streak. `:not_applicable` is a target with no lineage to audit at
+      # all; `:error` is the audit failing to run, which the caller
+      # surfaces as a finding rather than holding.
       def diverged_ancestor_writes(domain_path)
         registry, directory = load_registry(domain_path)
         bluebook = registry.bluebooks.values.first
-        return unchecked("no bluebook in #{directory}") unless bluebook
+        return failed("no bluebook in #{directory}") unless bluebook
 
         first = bluebook.aggregates.first
-        return unchecked("#{bluebook.name} declares no aggregates") unless first
+        return not_applicable("#{bluebook.name} declares no aggregates") unless first
 
         adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
-        return unchecked("#{bluebook.name} is bound to #{adapter_name}, not PostgresEra") unless adapter_name == "PostgresEra"
+        unless adapter_name == "PostgresEra"
+          return not_applicable("#{bluebook.name} is bound to #{adapter_name}, not PostgresEra")
+        end
 
         settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
         db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
@@ -81,14 +91,23 @@ module Hecks
           db.close
         end
       rescue StandardError => e
-        unchecked("#{e.class}: #{e.message}")
+        # Could not audit is not the same as nothing to audit — a refused
+        # connection, a `Lineage` defect, malformed `.world` settings. Every
+        # one of these used to answer the benign shape and be held.
+        failed("#{e.class}: #{e.message}")
       end
 
-      def unchecked(reason) = { checked: false, reason: reason }
+      # Nothing to audit — this target holds no PostgresEra lineage, so no
+      # ancestor era can carry post-cut writes. Not a finding, and not
+      # evidence of anything either: the caller logs no Check at all.
+      def not_applicable(reason) = { checked: false, kind: :not_applicable, reason: reason }
+
+      # The audit itself could not run — reported as a finding, never held.
+      def failed(reason) = { checked: false, kind: :error, reason: reason }
 
-      # THE SAME LOAD `bin/merge_tail` ITSELF PERFORMS (that script's own
+      # The same load `bin/merge_tail` itself performs (that script's own
       # top half) — a fresh `Registry`, never the ledger's own (this asks
-      # about the SWEPT TARGET's lineage, not QualityControl's own).
+      # about the swept target's lineage, not QualityControl's own).
       def load_registry(domain_path)
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)

data/lib/hecks/fuzzing/form_census.rb

@@ -1,27 +1,28 @@
 require "json"
+require_relative "../corpus"
 
 module Hecks
   module Fuzzing
-    # WHAT AN AGGREGATE CAN EXHIBIT, AND WHICH PAIRS IT PUTS TOGETHER.
+    # What an aggregate can exhibit, and which pairs it puts together.
     #
     # Extracted from `spec/combination_coverage_spec.rb`'s own pairwise
     # table so it has exactly two consumers that can never drift: that
     # spec (the golden corpus, held to every pair) and `bin/qa_domain_
-    # novelty` (a CANDIDATE stress domain, measured against every path
+    # novelty` (a candidate stress domain, measured against every path
     # the QA ledger already sweeps — see that script's own header for why
     # a new domain has to name the pair no existing target meets before
     # it earns a place in the rotation).
     #
-    # THE UNIT IS ONE AGGREGATE. Two forms in the same chapter but
+    # **The unit is one aggregate**. Two forms in the same chapter but
     # different heads never meet at dispatch; two forms on one head do
     # — that spec's own header has the four defects that argument came
     # from. Each entry below is a form the language declares and a
     # runtime has to handle, chosen because it has produced a defect or
     # sits one step from one; adding one here is how a new form joins
-    # BOTH gates at once, and it will name its own uncovered pairs on the
+    # both gates at once, and it will name its own uncovered pairs on the
     # first run of each.
     #
-    # ONE FLAT TABLE, ON PURPOSE — each entry is an independent boolean
+    # **One flat table, on purpose** — each entry is an independent boolean
     # check against the same string-keyed aggregate IR hash (the shape
     # `spec/golden/ir/*.json` carries and `Projector::Exporter.call`
     # round-trips to through JSON), laid out so every declared form can
@@ -48,7 +49,7 @@ module Hecks
         "closed_set"         => ->(a) { (a["value_objects"] || []).any? { |shape| shape["closed_set"] } },
         "has_default"        => ->(a) { attributes(a).any? { |held| !held["default"].nil? } },
         "has_optional"       => ->(a) { commands(a).any? { |verb| (verb["attributes"] || []).any? { |held| held["optional"] } } },
-        # THE REFERENCE-HOP FAMILY (ANGLE-2, qa/bluebook ledger) — the
+        # The reference-hop family (angle-2, qa/bluebook ledger) — the
         # forms `qa/stress_domains/referral_chain` exists for, absent
         # from the census until that domain named them. Each is one
         # step from a catalogued gap: `two_hop_given` is `dereference`'s
@@ -59,6 +60,19 @@ module Hecks
         # command redeclaring the aggregate's own reference field under
         # a non-reference type, so only `resolve_state_references` (never
         # ported) can catch a dangling id.
+        # A retroactive correction, and a role-gated command — both are
+        # declared forms this census could not see, on aggregates it was
+        # already measuring: `examples/banking` has carried `corrects`
+        # mutations and `role`-bearing commands the whole time, and
+        # `qa/stress_domains/corrections` exists for the first. Three
+        # stress domains' own NOTES.md record `bin/qa_domain_novelty`
+        # answering "no new pair" for a domain whose whole point was a
+        # shape this table did not name (case_escalation's is the
+        # bluntest: "read that as a gap in the census, not in this
+        # domain"). Entity commands count for both — BUG#30-33 and
+        # BUG#31 were all entity-level `corrects`.
+        "corrects"           => ->(a) { every_command(a).any? { |verb| corrects?(verb) } },
+        "role_gated"         => ->(a) { every_command(a).any? { |verb| !verb["role"].to_s.empty? } },
         "two_hop_given"      => ->(a) { two_hop_given?(a) },
         "multi_hop_where"    => ->(a) { multi_hop_where?(a) },
         "revalued_reference" => ->(a) { revalued_reference?(a) }
@@ -68,6 +82,13 @@ module Hecks
 
       def entities(aggregate)   = aggregate["entities"] || []
       def commands(aggregate)   = aggregate["commands"] || []
+
+      # One aggregate's commands, its pieces' included — a form carried by
+      # an entity command is carried by the aggregate that owns it, the
+      # same way `composite_piece`/`piece_lifecycle` already read pieces.
+      def every_command(aggregate) = commands(aggregate) + entities(aggregate).flat_map { |piece| commands(piece) }
+
+      def corrects?(verb) = (verb["mutations"] || []).any? { |change| change["op"].to_s == "corrects" }
       def attributes(aggregate) = aggregate["attributes"] || []
       def queries(aggregate)    = aggregate["queries"] || []
       def reference?(attribute) = attribute["type"].to_s.start_with?("Reference<")
@@ -82,7 +103,7 @@ module Hecks
       end
 
       # A command attribute sharing a name with one of the aggregate's
-      # own reference-typed attributes while carrying a DIFFERENT, non-
+      # own reference-typed attributes while carrying a different, non-
       # reference type — `attribute :member, Handle` against
       # `reference_to Member`.
       def revalued_reference?(aggregate)
@@ -121,7 +142,7 @@ module Hecks
       def pair_key(left, right) = [left, right].sort.join(" + ")
 
       # `held` is `[[aggregate_name, properties], ...]`. Answers which
-      # pairs are met on ONE aggregate, and by which — a Hash from pair
+      # pairs are met on one aggregate, and by which — a Hash from pair
       # key to the names carrying it, so a caller can say who.
       def covered_pairs(held)
         held.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(name, shows), covered|
@@ -140,23 +161,17 @@ module Hecks
         end
       end
 
-      # WHERE A DOMAIN PATH KEEPS ITS BLUEBOOKS — `<domain>/bluebook/*.
-      # bluebook` (every example and stress domain), or the directory
-      # itself (`qa/bluebook`, the ledger's own `Target.path`): the same
-      # two shapes `bin/model_check`'s `bluebook_in` reads. `nil` when
-      # neither holds a bluebook.
+      # Where a domain path keeps its bluebooks — see
+      # `Hecks::Corpus.bluebook_files`, the one definition every corpus
+      # walk shares. `nil` when neither shape holds a bluebook.
       def bluebook_files(domain_path)
-        [File.join(domain_path, "bluebook"), domain_path].each do |dir|
-          files = Dir[File.join(dir, "*.bluebook")]
-          return files unless files.empty?
-        end
-        nil
+        Hecks::Corpus.bluebook_files(domain_path)
       end
 
-      # THE SAME CENSUS OVER A DOMAIN ON DISK, booted the lightweight
+      # The same census over a domain on disk, booted the lightweight
       # way `bin/model_check` and `Hecks::Codemod.load_bluebook` already
       # do (ports and the two in-process adapters, no `Hecks.boot`, no
-      # live database, no `.hecksagon`: the census reads declared SHAPE,
+      # live database, no `.hecksagon`: the census reads declared shape,
       # and a framework chapter a `.hecksagon` would attach is not this
       # domain's own). Only the domain's own chapter is measured — the
       # first bluebook loaded, the same "target chapter is always first"

data/lib/hecks/fuzzing/generated_domain_check.rb

@@ -0,0 +1,95 @@
+require "json"
+require_relative "isolated_boot"
+require_relative "sequence_generator"
+require_relative "replay"
+require_relative "shrinker"
+require_relative "differential"
+
+module Hecks
+  module Fuzzing
+    # **One generated domain, checked** — the child-process half of
+    # `bin/qa_generated_domains` (one domain per process: every generated
+    # domain is named `QaGenerated`, see DomainGenerator's header).
+    #
+    # The same comparisons `bin/qa_sweep` runs on a rotation target, over
+    # sequences generated against a domain nobody wrote: with a compiled
+    # binary, `Differential.diff` (Ruby vs Rust, self-consistency, declared
+    # properties); without one, a Ruby-only replay (properties,
+    # self-consistency, an interpreter crash). A domain that does not even
+    # boot is `invalid` — a generator defect, not a finding, reported apart.
+    #
+    # `match:` is how domain-level shrinking asks "does this smaller domain
+    # still show the same finding?": only a divergence in the same mode
+    # whose `Shrinker.signature` contains the original's counts. Verb names
+    # survive a removal that did not touch them, so the signature does too.
+    module GeneratedDomainCheck
+      DIFFERENTIAL_MODES = %i[differential self_consistency properties_in_differential].freeze
+
+      module_function
+
+      def run(domain_path, seeds:, steps:, adversarial:, binary: nil, differ: nil, match: nil, shrink_budget: 0)
+        error = boot_error(domain_path)
+        return { "status" => "invalid", "error" => error } if error
+
+        (1..seeds).each do |seed|
+          finding = check_seed(domain_path, seed, steps, adversarial, binary, differ, match)
+          next unless finding
+
+          finding["shrunk_steps"] = shrink(domain_path, finding, binary, differ, shrink_budget) if shrink_budget.positive?
+          return finding.merge("status" => "found", "seeds_run" => seed)
+        end
+        { "status" => "clean", "seeds_run" => seeds }
+      end
+
+      def boot_error(domain_path)
+        IsolatedBoot.call(domain_path) { |copy| Hecks.boot(copy) }
+        nil
+      rescue StandardError, ScriptError => e
+        "#{e.class}: #{e.message.lines.first&.strip}"
+      end
+
+      def check_seed(domain_path, seed, steps, adversarial, binary, differ, match)
+        sequence = SequenceGenerator.generate(domain_path, seed: seed, steps: steps, adversarial: adversarial)
+      rescue StandardError => e
+        finding(seed, :generator, [{ field: "generator_crash", detail: "#{e.class}: #{e.message}" }], [], match)
+      else
+        outcomes(domain_path, sequence, binary, differ).each do |mode, divergences|
+          found = finding(seed, mode, divergences, sequence, match)
+          return found if found
+        end
+        nil
+      end
+
+      def outcomes(domain_path, sequence, binary, differ)
+        return Differential.diff(differ, domain_path, sequence, binary, modes: DIFFERENTIAL_MODES) if binary
+
+        history = Replay.call(domain_path, sequence, self_consistency: true)
+        { ruby_only:        Differential.property_divergences(history),
+          self_consistency: Differential.self_consistency_divergences(history) }
+      rescue StandardError => e
+        { ruby_only: [{ field: "crash", detail: "#{e.class}: #{e.message}" }] }
+      end
+
+      def finding(seed, mode, divergences, sequence, match)
+        return nil if divergences.empty?
+
+        signature = Shrinker.signature(divergences)
+        return nil if match && !(match["mode"] == mode.to_s && Set.new(match["signature"]).subset?(signature))
+
+        { "seed" => seed, "mode" => mode.to_s, "signature" => signature.to_a.sort, "steps" => sequence,
+          "divergences" => JSON.parse(JSON.generate(divergences)) }
+      end
+
+      # The step-level half of shrinking, in this same process: the domain
+      # is already as small as the parent could make it.
+      def shrink(domain_path, found, binary, differ, budget)
+        original = Set.new(found["signature"])
+        mode = found["mode"].to_sym
+        Shrinker.call(found["steps"], budget: budget) do |candidate|
+          divergences = outcomes(domain_path, candidate, binary, differ)[mode] || []
+          Shrinker.reproduces?(original, divergences)
+        end.steps
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/invalid_value_generator.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Fuzzing
-    # A value that is DELIBERATELY THE WRONG SHAPE for the attribute it is handed
+    # A value that is deliberately the wrong shape for the attribute it is handed
     # to — the sibling of ValueGenerator, which only ever builds values that satisfy
     # a declared type.
     #
@@ -14,7 +14,7 @@ module Hecks
     # Rendering's whole story), and no generated value
     # could ever have produced it.
     #
-    # These are expected to be REFUSED, and that is the point : a refusal is an
+    # These are expected to be refused, and that is the point : a refusal is an
     # answer, and its wording is pinned byte-for-byte. The bugs live in
     # the sentence, not in the happy path.
     module InvalidValueGenerator
@@ -37,7 +37,7 @@ module Hecks
         build(kind, attribute, aggregate, random: random)
       end
 
-      # Only the confusions that MEAN anything for this attribute. Offering
+      # Only the confusions that mean anything for this attribute. Offering
       # `scalar_for_object` for a plain Integer would just be a second spelling of
       # `numeral_string`, and a kind that cannot be wrong for the attribute it is
       # handed teaches the corpus nothing.
@@ -60,16 +60,16 @@ module Hecks
         end
       end
 
-      # A bare scalar where a value object is declared. A SINGLE-FIELD value object
+      # A bare scalar where a value object is declared. A single-field value object
       # legitimately accepts one (that is the standing-in rule every domain relies
-      # on), so the interesting case is a value object with SEVERAL fields, where a
+      # on), so the interesting case is a value object with several fields, where a
       # scalar cannot stand for anything and the refusal has to say so.
       def scalar_for(attribute, aggregate, random:)
         value_object = aggregate.value_object(attribute.type.to_s)
         sole = value_object&.sole_attribute
         return "a bare scalar" unless sole
 
-        # One field, so a scalar is legal — corrupt the FIELD's own type instead,
+        # One field, so a scalar is legal — corrupt the field's own type instead,
         # which is still a shape the attribute cannot accept.
         { sole.name.to_s => ["nested", "array"] }
       end