hecks 1.2.0 → 1.4.0

data/lib/hecks/fuzzing/era_boundary.rb

@@ -0,0 +1,124 @@
+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
+    # question; this one asks a single, unconditional question of a
+    # 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
+    # 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
+    # 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
+    # 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
+    # connection walking straight through the era write-fence — fixed by
+    # refusing that connection outright, `Lineage#check_fence_applies!`).
+    # Both are "a fork happened and nothing said so" — this module is the
+    # automatic version of the question `bin/merge_tail`'s own diagnostic
+    # 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
+    # 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
+    # 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
+    # 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
+    # reported `checked: false` with the reason — an operational note this
+    # mode's own caller surfaces once, never a crash and never silently
+    # "clean".
+    module EraBoundary
+      module_function
+
+      # `{ checked: true, diverged_total:, breakdown: [{ordinal:, diverged:}] }`
+      # 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 failed("no bluebook in #{directory}") unless bluebook
+
+        first = bluebook.aggregates.first
+        return not_applicable("#{bluebook.name} declares no aggregates") unless first
+
+        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+        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)
+        begin
+          lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+          lineage.ensure_base!
+          eras = lineage.eras
+          # `bin/merge_tail`'s own arithmetic, restated read-only: every
+          # ancestor era (every ordinal strictly before the head's own) may
+          # still hold post-cut writes the head has never interleaved.
+          breakdown = if eras.size > 1
+                        (1...eras.last[:ordinal]).map do |ordinal|
+                          { ordinal: ordinal, diverged: lineage.diverged_count(ordinal) }
+                        end
+                      else
+                        []
+                      end
+          { checked: true, era_count: eras.size, breakdown: breakdown, diverged_total: breakdown.sum { |b| b[:diverged] } }
+        ensure
+          db.close
+        end
+      rescue StandardError => e
+        # 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
+
+      # 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
+      # top half) — a fresh `Registry`, never the ledger's own (this asks
+      # 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)
+        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(loading.shared_root(nil, directory))
+          loading.load_domain(directory)
+        end
+        [registry, directory]
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/form_census.rb

@@ -0,0 +1,199 @@
+require "json"
+require_relative "../corpus"
+
+module Hecks
+  module Fuzzing
+    # 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
+    # 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
+    # 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
+    # first run of each.
+    #
+    # **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
+    # be read, and added to, at a glance.
+    module FormCensus
+      # A `given`'s own lookup path crossing at least two references —
+      # `member.sponsor.standing`, `source.customer.status`: the
+      # `CommandRules::References#dereference` recursion, walked only
+      # on a fresh command argument (S12, ADR 0025) and hydrated one
+      # repository lookup per hop.
+      TWO_HOP_GIVEN_PATH_LENGTH = 3
+
+      FORMS = {
+        "composite_id"       => ->(a) { (a["identified_by"] || []).size >= 2 },
+        "has_entity"         => ->(a) { entities(a).any? },
+        "two_entities"       => ->(a) { entities(a).size >= 2 },
+        "composite_piece"    => ->(a) { entities(a).any? { |piece| (piece["identified_by"] || []).size >= 2 } },
+        "multi_emit"         => ->(a) { commands(a).any? { |verb| (verb["emits"] || []).size >= 2 } },
+        "lifecycle"          => ->(a) { !a["lifecycle"].nil? },
+        "piece_lifecycle"    => ->(a) { entities(a).any? { |piece| !piece["lifecycle"].nil? } },
+        "has_query"          => ->(a) { queries(a).any? },
+        "list_attr"          => ->(a) { attributes(a).any? { |held| held["list"] } },
+        "reference_attr"     => ->(a) { attributes(a).any? { |held| reference?(held) } },
+        "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
+        # 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
+        # own recursion (`DEREFERENCE_DEPTH`); `multi_hop_where` is a
+        # `/`-chain `HopPath` walks for real and `rust/project/queries.
+        # rb` structurally refuses (D2 of the equivalence-gap plan);
+        # `revalued_reference` is ADR 0037 Finding 5's exact trigger — a
+        # 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) }
+      }.freeze
+
+      module_function
+
+      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<")
+
+      def two_hop_given?(aggregate)
+        commands(aggregate).any? { |verb| (verb["givens"] || []).any? { |given| deep_lookup?(given["ast"]) } }
+      end
+
+      # A `where` whose field crosses two `/` — `member/sponsor/standing`.
+      def multi_hop_where?(aggregate)
+        queries(aggregate).any? { |query| (query["wheres"] || []).any? { |where| where["field"].to_s.count("/") >= 2 } }
+      end
+
+      # A command attribute sharing a name with one of the aggregate's
+      # own reference-typed attributes while carrying a different, non-
+      # reference type — `attribute :member, Handle` against
+      # `reference_to Member`.
+      def revalued_reference?(aggregate)
+        references = attributes(aggregate).select { |held| reference?(held) }.to_set { |held| held["name"].to_s }
+        commands(aggregate).any? do |verb|
+          (verb["attributes"] || []).any? { |held| references.include?(held["name"].to_s) && !reference?(held) }
+        end
+      end
+
+      # Walks a given's own exported AST for any `lookup` whose path is
+      # long enough to have crossed two references.
+      def deep_lookup?(node)
+        case node
+        when Hash
+          return true if node["op"] == "lookup" && Array(node["path"]).size >= TWO_HOP_GIVEN_PATH_LENGTH
+
+          node.each_value.any? { |child| deep_lookup?(child) }
+        when Array
+          node.any? { |child| deep_lookup?(child) }
+        else
+          false
+        end
+      end
+
+      # Every form, answered for one aggregate — the table above, applied.
+      def properties(aggregate)
+        FORMS.transform_values { |form| form.call(aggregate) }
+      end
+
+      # Every unordered pair of forms, each rendered "left + right" in
+      # alphabetical order — the key both gates' excuse tables use.
+      def pairs
+        FORMS.keys.combination(2).map { |pair| pair_key(*pair) }
+      end
+
+      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
+      # 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|
+          shows.select { |_, present| present }.keys.combination(2).each do |left, right|
+            covered[pair_key(left, right)] << name
+          end
+        end
+      end
+
+      # `[[\"Chapter::Aggregate\", properties], ...]` for every aggregate
+      # a string-keyed chapter IR declares — the same walk the golden
+      # spec makes over `spec/golden/ir/*.json`.
+      def aggregates_in(chapter_ir)
+        (chapter_ir["aggregates"] || []).map do |aggregate|
+          ["#{chapter_ir['name']}::#{aggregate['name']}", properties(aggregate)]
+        end
+      end
+
+      # 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)
+        Hecks::Corpus.bluebook_files(domain_path)
+      end
+
+      # 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,
+      # 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"
+      # fact `bin/project_rust` relies on.
+      def census(domain_path)
+        root = File.expand_path("../../..", __dir__)
+        files = bluebook_files(domain_path)
+        raise ArgumentError, "#{domain_path} has no bluebook/*.bluebook (or *.bluebook) to measure" if files.nil?
+
+        registry = Hecks::Runtime::Registry.new(root: File.expand_path(domain_path))
+        Hecks.with_registry(registry) do
+          Kernel.load(File.join(root, "lib/hecks/ports/persistence.port"))
+          Kernel.load(File.join(root, "lib/hecks/ports/extraction.port"))
+          Kernel.load(File.join(root, "lib/hecks/adapters/driven/memory.adapter"))
+          Kernel.load(File.join(root, "lib/hecks/adapters/driven/prism.adapter"))
+          files.each { |file| Kernel.load(file) }
+        end
+
+        chapter_name = registry.bluebooks.keys.first
+        exported = JSON.parse(JSON.generate(Hecks::Projector::Exporter.call(registry).fetch(chapter_name)))
+        aggregates_in(exported)
+      end
+    end
+  end
+end

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