rigortype 0.3.8 → 0.4.0

data/lib/rigor/environment.rb

@@ -13,8 +13,10 @@ require_relative "environment/constant_type_cache_holder"
 require_relative "environment/missing_gem_constant_index"
 require_relative "environment/bundle_sig_discovery"
 require_relative "environment/lockfile_resolver"
+require_relative "environment/installed_gem_set"
 require_relative "environment/rbs_collection_discovery"
 require_relative "plugin/isolation"
+require_relative "cache/engine_source"
 require_relative "environment/rbs_coverage_report"
 require_relative "inference/synthetic_method_index"
 require_relative "inference/project_patched_methods"
@@ -48,16 +50,15 @@ module Rigor
                 :reporters, :name_scope,
                 :synthetic_method_index, :project_patched_methods
 
-    # @param class_registry [Rigor::Environment::ClassRegistry]
-    # @param rbs_loader [Rigor::Environment::RbsLoader, nil] when nil the environment is "RBS-blind"; useful
+    # @param rbs_loader — when nil the environment is "RBS-blind"; useful
     #   in tests that want to assert how the engine behaves without RBS data. The default Environment wires
     #   the shared core loader, which is itself lazy: requesting an environment instance does NOT load RBS
     #   until a method or class query actually consults the loader.
-    # @param plugin_registry [Rigor::Plugin::Registry, nil] v0.1.1 Track 2 slice 7. The per-run plugin
+    # @param plugin_registry — v0.1.1 Track 2 slice 7. The per-run plugin
     #   registry the inference engine consults at call sites for plugin `dynamic_return` rules. When nil
     #   (the default), no plugin-level return-type contribution participates — useful for tests, the
     #   `Environment.default` facade, and analyses that don't load plugins.
-    # @param dependency_source_index [Rigor::Analysis::DependencySourceInference::Index, nil] ADR-10 slice
+    # @param dependency_source_index — ADR-10 slice
     #   2b-ii. The per-run index of opt-in gem sources the dispatcher consults BELOW RBS dispatch. When nil
     #   (the default), no dep-source contribution participates and the dispatcher tier is a no-op.
     def initialize(class_registry: ClassRegistry.default, rbs_loader: nil, # rubocop:disable Metrics/ParameterLists
@@ -151,7 +152,7 @@ module Rigor
     # defect. First-write-wins on the slot means a run whose overlay AND scan both raise reports the
     # overlay — the actionable one, since the plugin is what a user can remove.
     #
-    # @return [Rigor::Inference::HktRegistry] the registry the RBS scan is layered on top of.
+    # @return the registry the RBS scan is layered on top of.
     def pre_scan_hkt_registry
       return @hkt_registry_base unless @plugin_registry.respond_to?(:hkt_overlay_registry)
 
@@ -171,8 +172,6 @@ module Rigor
     # worker (the coordinator never analyses a file under the pool, so the drain is how its snapshot learns
     # the outcome: the #696 lesson), and from a resolved environment when the analyze set is empty — so the
     # row never depends on which files happened to be analysed.
-    #
-    # @return [Array(String, String, String, Symbol), Array(String, String, nil, Symbol), nil]
     def hkt_scan_failure
       @hkt_scan_failure.value
     end
@@ -255,18 +254,17 @@ module Rigor
       # Builds an Environment that consults the project's local signatures and any opt-in stdlib libraries on
       # top of RBS core.
       #
-      # @param root [String, Pathname] project root used to auto-detect the default signature path. Defaults
+      # @param root — project root used to auto-detect the default signature path. Defaults
       #   to the current working directory.
-      # @param libraries [Array<String, Symbol>] additional stdlib libraries to load on top of
+      # @param libraries — additional stdlib libraries to load on top of
       #   {DEFAULT_LIBRARIES}. The final list is the union of the two, de-duplicated while preserving order.
       #   Pass an empty array (the default) to load only the defaults.
-      # @param signature_paths [Array<String, Pathname>, nil] explicit list of `sig/`-style directories. When
+      # @param signature_paths — explicit list of `sig/`-style directories. When
       #   `nil` (the default), the canonical project layout `<root>/sig` is used if it exists, otherwise no
       #   signature path is loaded.
-      # @param cache_store [Rigor::Cache::Store, nil] persistent cache threaded into the underlying
+      # @param cache_store — persistent cache threaded into the underlying
       #   {Environment::RbsLoader} so constant lookups (and, in later v0.0.9 slices, other reflection
       #   artefacts) consult the cache. Pass `nil` (the default) to skip caching for this environment.
-      # @return [Rigor::Environment]
       # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
       def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil,
                       plugin_registry: nil, dependency_source_index: nil,
@@ -276,7 +274,7 @@ module Rigor
                       bundler_lockfile: nil,
                       rbs_collection_lockfile: nil, rbs_collection_auto_detect: false,
                       synthetic_method_index: nil, project_patched_methods: nil,
-                      source_files: [])
+                      source_files: [], locked_gems: nil)
         resolved_paths = signature_paths || default_signature_paths(root)
         # O4 MVP — append per-gem `sig/` directories discovered under the target project's bundler install
         # root. Empty array when neither an explicit path nor auto-detection finds a bundle. Order: user
@@ -287,7 +285,10 @@ module Rigor
         # to the project root), use the locked gem set to filter the discovered `sig/` directories. Stale
         # gems in the bundle install tree (out-of-band installs, version drift after a `bundle update`) are
         # silently dropped so only gems the project actually declares contribute RBS.
-        locked = LockfileResolver.locked_gems(
+        #
+        # #1064 — `locked_gems:` is that same map resolved by the caller. The Ractor pool passes it because
+        # Bundler's parser cannot run in a non-main Ractor; every other caller leaves it nil and resolves here.
+        locked = locked_gems || LockfileResolver.locked_gems(
           lockfile_path: bundler_lockfile,
           project_root: root,
           auto_detect: bundler_auto_detect
@@ -336,7 +337,7 @@ module Rigor
         missing_gems, overlay_paths = missing_gems_and_overlay_paths(
           locked: locked, default_libraries: merged_libraries, bundle_sig_paths: gem_sig_paths,
           rbs_collection_paths: collection_paths, plugin_registry: plugin_registry,
-          signature_paths: resolved_paths
+          signature_paths: resolved_paths, bundle_root: bundle_root
         )
         loader_signature_paths = resolved_paths + plugin_sig_paths + gem_sig_paths +
                                  collection_paths + overlay_paths
@@ -361,6 +362,14 @@ module Rigor
           # the bundle walk and `rbs collection install` all stay authoritative.
           deferred_signature_paths: plugin_sig_paths
         )
+        # Issues #824 / #1075 — the rows ADR-112 WD5's consistency rule reports for members the project's
+        # own `sig/` and an inline source both declare: an error per contradiction (or per refinement that
+        # exceeds its own declared type), an `:info` per inline member dropped undecided. Recorded HERE
+        # because this is where the reporter is: the run's `source_rbs_synthesis` stream already carries
+        # WD12's "parsed but not honoured" rows, drains out of pool workers, and is regenerated (never cached)
+        # on every run, so the member-level outcome needs no plumbing of its own. Costs nothing for a project
+        # with no inline RBS: the loader's reader short-circuits on an empty `virtual_rbs`.
+        record_member_consistency(loader, source_rbs_synthesis_reporter, root)
         # ADR-20 slice 2c + 2e — seed hkt_registry with the bundled builtins. The Environment's
         # `#hkt_registry` getter then LAZILY merges in the RBS env scan on first call so fast paths that
         # don't consult HKT (e.g. `rigor check --cache-stats --no-stats`) don't pay the eager env-build cost
@@ -412,13 +421,13 @@ module Rigor
       # and consumed twice: as `[gem_name, version]` pairs for the ADR-82 WD9 constant-ownership index, and
       # as the eligible-gem set for the ADR-72 overlay resolution. Returns `[pairs, overlay_paths]`.
       def missing_gems_and_overlay_paths(locked:, default_libraries:, bundle_sig_paths:,
-                                         rbs_collection_paths:, plugin_registry:, signature_paths: [])
-        return [[], []] if locked.empty?
+                                         rbs_collection_paths:, plugin_registry:, signature_paths: [],
+                                         bundle_root: nil)
+        if locked.empty?
+          return unlocked_missing_gems(default_libraries, bundle_sig_paths, rbs_collection_paths, bundle_root)
+        end
 
-        rows = RbsCoverageReport.classify(
-          locked_gems: locked, default_libraries: default_libraries,
-          bundle_sig_paths: bundle_sig_paths, rbs_collection_paths: rbs_collection_paths
-        ).select { |row| row.source == :missing }
+        rows = missing_rows(locked, default_libraries, bundle_sig_paths, rbs_collection_paths)
         overlays = gem_overlay_paths(
           missing_gem_names: rows.map(&:gem_name), plugin_registry: plugin_registry,
           signature_paths: signature_paths
@@ -426,6 +435,27 @@ module Rigor
         [rows.map { |row| [row.gem_name, row.version] }, overlays]
       end
 
+      # Issue #530 — a project with no `Gemfile.lock` still has gems on disk, and before this it handed the
+      # ADR-82 WD9 index nothing, so every constant reaching into an RBS-less gem kept the generic cause and
+      # the whole boundary reported as `engine_gap` rather than `add_rbs`. The installed set stands in for
+      # the locked one ({InstalledGemSet} says why that stays honest), and only for the provenance index:
+      # the second element is always empty because the ADR-72 overlays change what type-checks and so remain
+      # gated on the project's own declaration.
+      def unlocked_missing_gems(default_libraries, bundle_sig_paths, rbs_collection_paths, bundle_root)
+        installed = InstalledGemSet.gems(bundle_path: bundle_root)
+        return [[], []] if installed.empty?
+
+        rows = missing_rows(installed, default_libraries, bundle_sig_paths, rbs_collection_paths)
+        [rows.map { |row| [row.gem_name, row.version] }, []]
+      end
+
+      def missing_rows(gems, default_libraries, bundle_sig_paths, rbs_collection_paths)
+        RbsCoverageReport.classify(
+          locked_gems: gems, default_libraries: default_libraries,
+          bundle_sig_paths: bundle_sig_paths, rbs_collection_paths: rbs_collection_paths
+        ).select { |row| row.source == :missing }
+      end
+
       # ADR-72 — resolve the bundled RBS overlay directories to load for this project. A gem is eligible when
       # it is classified `:missing` (see {missing_rbs_gem_rows}) and its conflicting opt-in plugin twin (if
       # any) is NOT already reachable. Returns `[Pathname]`, deterministically ordered, or `[]` when no
@@ -467,7 +497,10 @@ module Rigor
       #
       # WD5 — when `cache_store` is supplied, each (file, plugin) synthesizer call is memoised through
       # `Cache::Store`. The cache key composes the file's content SHA with the plugin's `PluginEntry` (id +
-      # version + config_hash) so a config change or content change invalidates the entry automatically.
+      # version + config_hash) so a config change or content change invalidates the entry automatically, and
+      # with the engine's source identity (issue #1009): a plugin's manifest version does not move when a
+      # checkout edits its synthesizer, and a stale string here also keeps the `rbs.virtual_rbs` env key warm,
+      # so the new build's rules would read the old build's RBS.
       def collect_virtual_rbs(plugin_registry, source_files, cache_store, reporter)
         return [] if plugin_registry.nil?
 
@@ -498,6 +531,8 @@ module Rigor
         return invoke_synthesizer_safely(callable, path) unless File.file?(path)
 
         descriptor = build_synthesizer_cache_descriptor(plugin, path)
+        return invoke_synthesizer_safely(callable, path) if descriptor.nil?
+
         cache_store.fetch_or_compute(
           producer_id: SYNTHESIZER_CACHE_PRODUCER_ID,
           params: {},
@@ -540,6 +575,93 @@ module Rigor
         reporter&.record(plugin_id: plugin.manifest.id, path: path, message: message.to_s, kind: kind)
       end
 
+      # ADR-112 WD5 / issue #1075 — turn each reported {MemberConsistency::Record} into a row on the
+      # synthesis stream. A contradiction, or a refinement outside its own declared type, is a `:contradiction`
+      # entry ({Analysis::CheckRules::RULE_CONTRADICTING_SIGNATURE}, an error), positioned at the `.rbs`
+      # member when there is one: that file is real and its line is exact, where the inline member's position
+      # lives in the synthesized RBS buffer, a document nobody has. An undecided pair keeps ADR-32 WD12's
+      # `:not_honoured` row at the annotated `.rb` (line 1, as every entry on that stream is): the inline
+      # signature was parsed and dropped, and WD12 forbids swallowing that. The silent outcomes — equal, or
+      # merged to the more precise side — record nothing.
+      #
+      # The records are derived with a {MemberConsistency::RbsProof}, so a contradiction is proven from the
+      # RBS hierarchy of core and stdlib classes, never from the analyzer process's loaded constants.
+      def record_member_consistency(loader, reporter, root)
+        return if reporter.nil?
+
+        proof = MemberConsistency::RbsProof.new(loader)
+        loader.member_consistency(proof: proof).each do |record|
+          case record.outcome
+          when :contradiction then record_member_contradiction(reporter, record, root)
+          when :refinement then record_refinement_contradiction(reporter, record, root)
+          when :undecided then record_member_undecided(reporter, record, root)
+          end
+        end
+      end
+
+      def record_member_contradiction(reporter, record, root)
+        plugin_id, path = split_virtual_source_name(record.virtual_name)
+        return if path.nil?
+
+        reporter.record(
+          plugin_id: plugin_id, path: path_relative_to(record.signature_path, root), line: record.signature_line,
+          kind: :contradiction,
+          message: "`#{member_label(record)}` is declared here and by an inline annotation in " \
+                   "`#{path_relative_to(path, root)}`, and the two contradict: #{record.detail}. Rigor reads " \
+                   "this `.rbs` declaration. Regenerate the signature, or fix the annotation, so that one " \
+                   "of the two refines the other."
+        )
+      end
+
+      def record_refinement_contradiction(reporter, record, root)
+        plugin_id, path = split_virtual_source_name(record.virtual_name)
+        path = record.signature_path if path.nil?
+        return if path.nil?
+
+        reporter.record(
+          plugin_id: plugin_id.to_s, path: path_relative_to(path, root), line: record.signature_line,
+          kind: :contradiction,
+          message: "`#{member_label(record)}` refines its own signature to a type outside it: " \
+                   "#{record.detail}. A `rigor:v1:` refinement may narrow the ordinary RBS contract, never " \
+                   "contradict it, so one of the two is wrong."
+        )
+      end
+
+      def record_member_undecided(reporter, record, root)
+        plugin_id, path = split_virtual_source_name(record.virtual_name)
+        return if path.nil?
+
+        reporter.record(
+          plugin_id: plugin_id, path: path, kind: :not_honoured,
+          message: "`#{member_label(record)}` is also declared in " \
+                   "`#{path_relative_to(record.signature_path, root)}`, and Rigor cannot tell which of the two " \
+                   "is the more precise (#{record.detail}), so the `.rbs` declaration binds and the inline " \
+                   "signature was dropped. Left to collide the two would fail the class's definition build, " \
+                   "and every call on it — real methods and typos alike — would read `Dynamic[top]`. Make " \
+                   "one of the two a refinement of the other, or remove one, to settle which binds."
+        )
+      end
+
+      def member_label(record)
+        separator = record.kind == :singleton ? "." : "#"
+        "#{record.class_name}#{separator}#{record.method_name}"
+      end
+
+      # Splits a virtual buffer name back into the pair {.collect_virtual_rbs} composed it from
+      # (`virtual:<plugin id>:<source path>`). Limited to three fields so a path carrying a colon survives.
+      # Returns `[nil, nil]` for a name in any other shape — a synthesizer channel this method does not own.
+      def split_virtual_source_name(virtual_name)
+        prefix, plugin_id, path = virtual_name.to_s.split(":", 3)
+        return [nil, nil] unless prefix == "virtual" && plugin_id && !plugin_id.empty? && path && !path.empty?
+
+        [plugin_id, path]
+      end
+
+      def path_relative_to(path, root)
+        prefix = "#{root}#{File::SEPARATOR}"
+        path.to_s.start_with?(prefix) ? path.to_s.delete_prefix(prefix) : path.to_s
+      end
+
       SYNTHESIZER_CACHE_PRODUCER_ID = "plugin.source_rbs_synthesizer"
       private_constant :SYNTHESIZER_CACHE_PRODUCER_ID
 
@@ -558,8 +680,13 @@ module Rigor
             comparator: :digest,
             value: synthesizer_input_digest(path)
           )],
-          plugins: [plugin.plugin_entry]
+          plugins: [plugin.plugin_entry],
+          configs: Cache::EngineSource.key_config_entries
         )
+      rescue Cache::EngineSource::Unavailable
+        # An engine that cannot be identified must not be keyed by its inputs alone (issue #1009): nil runs the
+        # synthesizer uncached rather than serving an entry another build may have written.
+        nil
       end
 
       def synthesizer_input_digest(path)
@@ -623,6 +750,17 @@ module Rigor
       end
     end
 
+    # Issue #1362 — the translated type of the RBS declaration of the global variable `name` (`$stdout: IO` answers
+    # `Nominal[IO]`), or nil when no signature declares it or the environment carries no RBS loader. With
+    # `builtin: true` it answers only for a declaration in Ruby's own core or stdlib signatures, a global the
+    # interpreter sets; a project's or a gem's declaration then answers nil.
+    def global_for_name(name, builtin: false)
+      return nil if rbs_loader.nil?
+      return nil if builtin && !rbs_loader.core_or_stdlib_global?(name)
+
+      rbs_loader.global_type(name)
+    end
+
     # Returns true when the constant name is known to either the static registry or the RBS loader. Useful
     # for callers that only need a presence check without materialising a type carrier.
     def class_known?(name)
@@ -653,6 +791,15 @@ module Rigor
       rbs_loader.rbs_module?(name)
     end
 
+    # Issue #915 — the module names RBS puts in `name`'s SINGLETON ancestry, the declaration-side twin of
+    # `Scope#singleton_extends_of`. `Inference::Narrowing` reads it the same one-directional way: presence
+    # withholds a `Bot`, absence asserts nothing (a class the environment does not know answers `[]`).
+    def singleton_extended_modules(name)
+      return [] unless rbs_loader
+
+      rbs_loader.singleton_extended_module_names(normalize_class_name(name))
+    end
+
     # Compares two class/module names using analyzer-owned class data. Returns `:equal`, `:subclass`,
     # `:superclass`, `:disjoint`, or `:unknown`. The static registry handles built-ins cheaply; the RBS
     # loader handles project/stdlib classes without relying on host Ruby constants being loaded.
@@ -677,8 +824,11 @@ module Rigor
       rbs_loader.class_known?(name)
     end
 
+    # Allocates only when there is a prefix to strip: `String#delete_prefix` copies unconditionally, and
+    # this runs once per class-registry / hierarchy probe (~320k times on the lib self-check).
     def normalize_class_name(name)
-      name.to_s.delete_prefix("::")
+      name = name.to_s
+      name.start_with?("::") ? name.delete_prefix("::") : name
     end
 
     # ADR-13 slice 3b — composes the per-run plugin-supplied {Rigor::TypeNode::ResolverChain} into a single

data/lib/rigor/flow_contribution/merger.rb

@@ -53,8 +53,6 @@ module Rigor
 
       module_function
 
-      # @param contributions [Array<FlowContribution>]
-      # @return [MergeResult]
       def merge(contributions)
         contributions = Array(contributions)
         return MergeResult.new if contributions.empty?

data/lib/rigor/flow_contribution.rb

@@ -49,24 +49,24 @@ module Rigor
 
     attr_reader(*SLOT_NAMES, :provenance)
 
-    # @param return_type [Object, nil] normal-edge return type. Use `nil` when the contribution does not
+    # @param return_type — normal-edge return type. Use `nil` when the contribution does not
     #   refine the return type selected from the RBS contract.
-    # @param truthy_facts [Array, nil] facts that hold only on the truthy control-flow edge. Edge-local: a
+    # @param truthy_facts — facts that hold only on the truthy control-flow edge. Edge-local: a
     #   truthy-edge fact does NOT imply its falsey-edge complement (ADR-2 § "Plugin Contribution Merging").
-    # @param falsey_facts [Array, nil] dual of `truthy_facts`.
-    # @param post_return_facts [Array, nil] facts that hold after the call returns normally on every edge —
+    # @param falsey_facts — dual of `truthy_facts`.
+    # @param post_return_facts — facts that hold after the call returns normally on every edge —
     #   the carrier for assertion-style contributions.
-    # @param mutations [Array, nil] receiver and argument mutation effects.
-    # @param invalidations [Array, nil] targeted fact invalidations beyond what mutation effects already
+    # @param mutations — receiver and argument mutation effects.
+    # @param invalidations — targeted fact invalidations beyond what mutation effects already
     #   imply.
-    # @param exceptional [Object, nil] non-returning, raising, or unreachable effect.
-    # @param role_conformance [Array, nil] capability-role conformance facts the contribution provides.
-    # @param effects [Rigor::Effects::LabelSet, nil] ADR-103 WD5 — the effect labels this call edge
+    # @param exceptional — non-returning, raising, or unreachable effect.
+    # @param role_conformance — capability-role conformance facts the contribution provides.
+    # @param effects — ADR-103 WD5 — the effect labels this call edge
     #   attributes to its callee, as an upper bound. `nil` means "says nothing about effects", which is
     #   NOT the same as the empty set (which asserts the call performs none). Merged by union, the
     #   conservative direction: two sources that each name part of a call's footprint together name
     #   more of it, and neither can shrink the other's claim.
-    # @param provenance [Provenance] source-family, plugin-id, node, and cache-descriptor metadata. Defaults
+    # @param provenance — source-family, plugin-id, node, and cache-descriptor metadata. Defaults
     #   to `Provenance.builtin`.
     # rubocop:disable Metrics/ParameterLists
     def initialize(return_type: nil, truthy_facts: nil, falsey_facts: nil,
@@ -87,7 +87,7 @@ module Rigor
       freeze
     end
 
-    # @return [Boolean] true when every content slot is unset (nil or an empty collection). Provenance does
+    # @return true when every content slot is unset (nil or an empty collection). Provenance does
     #   not count toward emptiness — an empty bundle still carries source attribution.
     def empty?
       SLOT_NAMES.all? { |slot| slot_empty?(slot, public_send(slot)) }
@@ -116,8 +116,6 @@ module Rigor
     # | exceptional         | exceptional   | exception           | :raise                  |
     # | role_conformance    | normal        | role                | (per-role target)       |
     # | effects             | normal        | effects             | :effects                |
-    #
-    # @return [Array<Element>]
     def to_element_list # rubocop:disable Metrics/AbcSize
       elements = []
       elements << element_for(:return, :normal, :return_type, return_type) unless return_type.nil?

data/lib/rigor/hashing/xxh3.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Hashing
+    # Pure-Ruby XXH3-64 (seed 0, default secret) — the content hash for the `rigor lens` anchors of
+    # ADR-113 WD6, landed ahead of `rigor lens` itself (#1083). A port of the upstream xxHash scalar
+    # path (`xxhash.h`'s `XXH3_64bits` with `XXH3_kSecret`), pinned by the upstream sanity-check
+    # vectors and cross-checked against lisplens's `xxhash-rust` output; see
+    # `spec/rigor/hashing/xxh3_spec.rb`.
+    #
+    # Pure Ruby per ADR-31: a native `xxhash` gem is a supply-chain addition to hash a few hundred
+    # bytes per call. Only the seedless/default-secret variant is implemented — the `rigor lens`
+    # anchors are the sole consumer, and they match lisplens ADR-0008's form exactly:
+    #
+    # - {.anchor_hash} is `xxh3_64 & 0xffff` printed as 4 lowercase hex digits (a per-row anchor).
+    # - {.file_hash} is the full 64-bit value printed as 16 lowercase hex digits (a file-level guard).
+    #
+    # Every arithmetic op below is modulo 2^64; `& MASK64` marks the spots where the C code wraps.
+    module XXH3
+      # Constant and helper names keep upstream's `xxhash.h` identifiers (PRIME64_1, accumulate_512,
+      # …) so the port stays diffable against the reference scalar path.
+      # rubocop:disable Naming/VariableNumber
+      MASK64 = (1 << 64) - 1
+      MASK32 = (1 << 32) - 1
+
+      PRIME32_1 = 0x9E3779B1
+      PRIME32_2 = 0x85EBCA77
+      PRIME32_3 = 0xC2B2AE3D
+      PRIME64_1 = 0x9E3779B185EBCA87
+      PRIME64_2 = 0xC2B2AE3D27D4EB4F
+      PRIME64_3 = 0x165667B19E3779F9
+      PRIME64_4 = 0x85EBCA77C2B2AE63
+      PRIME64_5 = 0x27D4EB2F165667C5
+      PRIME_MX1 = 0x165667919E3779F9
+      PRIME_MX2 = 0x9FB21C651E98DF25
+
+      STRIPE_LEN = 64
+      SECRET_CONSUME_RATE = 8
+      ACC_NB = STRIPE_LEN / 8
+      MIDSIZE_MAX = 240
+      SECRET_SIZE_MIN = 136
+      MIDSIZE_STARTOFFSET = 3
+      MIDSIZE_LASTOFFSET = 17
+      SECRET_LASTACC_START = 7
+      SECRET_MERGEACCS_START = 11
+
+      # `XXH3_kSecret` — the 192-byte default secret taken from FARSH, verbatim from `xxhash.h`
+      # (one hex pair per upstream byte literal).
+      SECRET = [
+        "b8fe6c3923a44bbe7c01812cf721ad1cded46de9839097db7240a4a4b7b3671f" \
+        "cb79e64eccc0e578825ad07dccff7221b8084674f743248ee03590e6813a264c" \
+        "3c2852bb91c300cb88d0658b1b532ea371644897a20df94e3819ef46a9deacd8" \
+        "a8fa763fe39c343ff9dcbbc7c70b4f1d8a51e04bcdb45931c89f7ec9d9787364" \
+        "eac5ac8334d3ebc3c581a0fffa1363eb170ddd51b7f0da49d316552629d4689e" \
+        "2b16be587d47a1fc8ff8b8d17ad031ce45cb3a8f95160428afd7fbcabb4b407e"
+      ].pack("H*").freeze
+
+      # XXH3_INIT_ACC
+      INIT_ACC = [PRIME32_3, PRIME64_1, PRIME64_2, PRIME64_3, PRIME64_4, PRIME32_2, PRIME64_5, PRIME32_1].freeze
+
+      private_constant :MASK64, :MASK32, :PRIME32_1, :PRIME32_2, :PRIME32_3, :PRIME64_1, :PRIME64_2, :PRIME64_3,
+                       :PRIME64_4, :PRIME64_5, :PRIME_MX1, :PRIME_MX2, :STRIPE_LEN, :SECRET_CONSUME_RATE,
+                       :ACC_NB, :MIDSIZE_MAX, :SECRET_SIZE_MIN, :MIDSIZE_STARTOFFSET, :MIDSIZE_LASTOFFSET,
+                       :SECRET_LASTACC_START, :SECRET_MERGEACCS_START, :SECRET, :INIT_ACC
+
+      class << self
+        # XXH3_64bits of `bytes`, hashed as raw bytes — the string's encoding is ignored.
+        def digest64(bytes)
+          len = bytes.bytesize
+          if len <= 16 then len_0to16(bytes, len)
+          elsif len <= 128 then len_17to128(bytes, len)
+          elsif len <= MIDSIZE_MAX then len_129to240(bytes, len)
+          else hash_long(bytes, len)
+          end
+        end
+
+        # lisplens ADR-0008's `anchor_hash`: the low 16 bits of the digest as 4 lowercase hex digits.
+        def anchor_hash(bytes)
+          format("%04x", digest64(bytes) & 0xffff)
+        end
+
+        # lisplens ADR-0008's `file_hash`: the full digest as 16 lowercase hex digits.
+        def file_hash(bytes)
+          format("%016x", digest64(bytes))
+        end
+
+        private
+
+        # --- short keys: len <= 16 ---
+
+        def len_0to16(bytes, len)
+          if len > 8 then len_9to16(bytes, len)
+          elsif len >= 4 then len_4to8(bytes, len)
+          elsif len.positive? then len_1to3(bytes, len)
+          else
+            xxh64_avalanche(u64(SECRET, 56) ^ u64(SECRET, 64))
+          end
+        end
+
+        def len_1to3(bytes, len)
+          c1 = bytes.getbyte(0)
+          c2 = bytes.getbyte(len >> 1)
+          c3 = bytes.getbyte(len - 1)
+          combined = (c1 << 16) | (c2 << 24) | c3 | (len << 8)
+          bitflip = u32(SECRET, 0) ^ u32(SECRET, 4)
+          xxh64_avalanche(combined ^ bitflip)
+        end
+
+        def len_4to8(bytes, len)
+          input1 = u32(bytes, 0)
+          input2 = u32(bytes, len - 4)
+          bitflip = u64(SECRET, 8) ^ u64(SECRET, 16)
+          keyed = (input2 + (input1 << 32)) ^ bitflip
+          rrmxmx(keyed, len)
+        end
+
+        def len_9to16(bytes, len)
+          bitflip1 = u64(SECRET, 24) ^ u64(SECRET, 32)
+          bitflip2 = u64(SECRET, 40) ^ u64(SECRET, 48)
+          input_lo = u64(bytes, 0) ^ bitflip1
+          input_hi = u64(bytes, len - 8) ^ bitflip2
+          acc = (len + swap64(input_lo) + input_hi + mul128_fold64(input_lo, input_hi)) & MASK64
+          xxh3_avalanche(acc)
+        end
+
+        # --- mid-size keys: 17 <= len <= 240 (mum-hash on 16-byte chunks) ---
+
+        def mix16b(bytes, in_off, sec_off)
+          input_lo = u64(bytes, in_off)
+          input_hi = u64(bytes, in_off + 8)
+          mul128_fold64(input_lo ^ u64(SECRET, sec_off), input_hi ^ u64(SECRET, sec_off + 8))
+        end
+
+        def len_17to128(bytes, len)
+          acc = len * PRIME64_1
+          if len > 32
+            if len > 64
+              if len > 96
+                acc += mix16b(bytes, 48, 96)
+                acc += mix16b(bytes, len - 64, 112)
+              end
+              acc += mix16b(bytes, 32, 64)
+              acc += mix16b(bytes, len - 48, 80)
+            end
+            acc += mix16b(bytes, 16, 32)
+            acc += mix16b(bytes, len - 32, 48)
+          end
+          acc += mix16b(bytes, 0, 0)
+          acc += mix16b(bytes, len - 16, 16)
+          xxh3_avalanche(acc & MASK64)
+        end
+
+        def len_129to240(bytes, len)
+          acc = len * PRIME64_1
+          nb_rounds = len / 16
+          8.times { |i| acc += mix16b(bytes, 16 * i, 16 * i) }
+          acc_end = mix16b(bytes, len - 16, SECRET_SIZE_MIN - MIDSIZE_LASTOFFSET)
+          acc = xxh3_avalanche(acc & MASK64)
+          (8...nb_rounds).each do |i|
+            acc_end += mix16b(bytes, 16 * i, (16 * (i - 8)) + MIDSIZE_STARTOFFSET)
+          end
+          xxh3_avalanche((acc + acc_end) & MASK64)
+        end
+
+        # --- long keys: len > 240 (striped accumulate + scramble, then merge) ---
+
+        def hash_long(bytes, len)
+          acc = INIT_ACC.dup
+          secret_size = SECRET.bytesize
+          nb_stripes_per_block = (secret_size - STRIPE_LEN) / SECRET_CONSUME_RATE
+          block_len = STRIPE_LEN * nb_stripes_per_block
+          nb_blocks = (len - 1) / block_len
+
+          nb_blocks.times do |n|
+            accumulate_stripes(acc, bytes, n * block_len, nb_stripes_per_block)
+            scramble(acc, secret_size - STRIPE_LEN)
+          end
+
+          last_off = nb_blocks * block_len
+          accumulate_stripes(acc, bytes, last_off, (len - 1 - last_off) / STRIPE_LEN)
+          accumulate_512(acc, bytes, len - STRIPE_LEN, secret_size - STRIPE_LEN - SECRET_LASTACC_START)
+
+          merge_accs(acc, len * PRIME64_1)
+        end
+
+        def accumulate_stripes(acc, bytes, base_off, nb_stripes)
+          nb_stripes.times do |s|
+            accumulate_512(acc, bytes, base_off + (s * STRIPE_LEN), s * SECRET_CONSUME_RATE)
+          end
+        end
+
+        # XXH3_accumulate_512_scalar: each 64-byte stripe folds into the 8-lane accumulator — the
+        # data value is added to the swapped adjacent lane, and the secret-keyed value contributes a
+        # 32x32->64 product to its own lane.
+        def accumulate_512(acc, bytes, in_off, sec_off)
+          ACC_NB.times do |i|
+            data_val = u64(bytes, in_off + (8 * i))
+            data_key = data_val ^ u64(SECRET, sec_off + (8 * i))
+            acc[i ^ 1] = (acc[i ^ 1] + data_val) & MASK64
+            acc[i] = (acc[i] + ((data_key & MASK32) * (data_key >> 32))) & MASK64
+          end
+        end
+
+        # XXH3_scrambleAcc_scalar
+        def scramble(acc, sec_off)
+          ACC_NB.times do |i|
+            acc[i] = ((acc[i] ^ (acc[i] >> 47) ^ u64(SECRET, sec_off + (8 * i))) * PRIME32_1) & MASK64
+          end
+        end
+
+        # XXH3_mergeAccs over the default secret, at SECRET_MERGEACCS_START.
+        def merge_accs(acc, start)
+          result = start
+          4.times do |i|
+            result += mul128_fold64(acc[2 * i] ^ u64(SECRET, SECRET_MERGEACCS_START + (16 * i)),
+                                    acc[(2 * i) + 1] ^ u64(SECRET, SECRET_MERGEACCS_START + (16 * i) + 8))
+          end
+          xxh3_avalanche(result & MASK64)
+        end
+
+        # --- primitives ---
+
+        def u32(bytes, off) = bytes.unpack1("L<", offset: off)
+
+        def u64(bytes, off) = bytes.unpack1("Q<", offset: off)
+
+        def swap64(value) = [value].pack("Q>").unpack1("Q<")
+
+        def rotl64(value, shift) = ((value << shift) | (value >> (64 - shift))) & MASK64
+
+        def mul128_fold64(lhs, rhs)
+          product = lhs * rhs
+          (product & MASK64) ^ (product >> 64)
+        end
+
+        # XXH3_avalanche — the fast finalizer used when the input is already partially mixed.
+        def xxh3_avalanche(hash)
+          hash = (hash ^ (hash >> 37)) & MASK64
+          hash = (hash * PRIME_MX1) & MASK64
+          hash ^ (hash >> 32)
+        end
+
+        # XXH64_avalanche — the stronger finalizer for the shortest keys.
+        def xxh64_avalanche(hash)
+          hash ^= hash >> 33
+          hash = (hash * PRIME64_2) & MASK64
+          hash ^= hash >> 29
+          hash = (hash * PRIME64_3) & MASK64
+          hash ^ (hash >> 32)
+        end
+
+        # XXH3_rrmxmx — the len 4-8 finalizer (Pelle Evensen's mix).
+        def rrmxmx(hash, len)
+          hash = (hash ^ rotl64(hash, 49) ^ rotl64(hash, 24)) & MASK64
+          hash = (hash * PRIME_MX2) & MASK64
+          hash ^= (hash >> 35) + len
+          hash = (hash * PRIME_MX2) & MASK64
+          hash ^ (hash >> 28)
+        end
+      end
+      # rubocop:enable Naming/VariableNumber
+    end
+  end
+end