rigortype 0.3.9 → 0.4.1

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

data/lib/rigor/inference/acceptance.rb

@@ -2,6 +2,7 @@
 
 require_relative "../type"
 require_relative "range_constant"
+require_relative "content_join"
 
 module Rigor
   module Inference
@@ -74,10 +75,64 @@ module Rigor
       }.freeze
       private_constant :TYPE_HANDLERS
 
+      UNREAD_HASH_REFUSED_KEY = :__rigor_acceptance_unread_hash_refused__
+      private_constant :UNREAD_HASH_REFUSED_KEY
+
+      # Whether a `maybe` for `param` against `arg` rests on a record that could not read a hash's entries: a
+      # `Hash` with a gradual arm ({#gradual_hash?}) or an open `HashShape`. The record cannot prove the key set
+      # of either, and its `maybe` climbs through whatever holds the record. `OverloadSelector`'s strict pass
+      # reads that `maybe` as no evidence for the overload, so this re-asks with each such record answering
+      # `no` and reports whether the pair then fails. A `maybe` from anywhere else (a subclass only the Ruby
+      # source declares, a splat under a parameter that is no record) survives the re-ask and still counts.
+      def maybe_rests_on_unread_hash?(param, arg)
+        return false unless contains_type?(param) { |type| type.is_a?(Type::HashShape) }
+        return false unless contains_type?(arg) { |type| unread_hash?(type) }
+
+        refusing_unread_hashes { accepts(param, arg, mode: :gradual).no? }
+      end
+
       # rubocop:disable-next Metrics/ClassLength
       class << self
         private
 
+        # The flag lives on the thread, not on a parameter, because the record may sit any number of `accepts`
+        # calls below the one asked (a tuple element, a `Hash` value, a union member), and those calls go
+        # through each carrier's `Type#accepts`. It is set only for the duration of the block.
+        def refusing_unread_hashes
+          previous = Thread.current[UNREAD_HASH_REFUSED_KEY]
+          Thread.current[UNREAD_HASH_REFUSED_KEY] = true
+          yield
+        ensure
+          Thread.current[UNREAD_HASH_REFUSED_KEY] = previous
+        end
+
+        # The `maybe` a record answers for a hash whose entries it cannot read, or `no` inside
+        # {#refusing_unread_hashes}.
+        def unread_hash_maybe(mode, reason)
+          return hash_shape_no(mode, "#{reason} (refused as evidence)") if Thread.current[UNREAD_HASH_REFUSED_KEY]
+
+          Type::AcceptsResult.maybe(mode: mode, reasons: reason)
+        end
+
+        def unread_hash?(type)
+          gradual_hash?(type) || (type.is_a?(Type::HashShape) && type.open?)
+        end
+
+        def contains_type?(type, &)
+          return true if yield(type)
+
+          components =
+            case type
+            when Type::Union then type.members
+            when Type::Nominal then type.type_args
+            when Type::Tuple then type.elements
+            when Type::HashShape then type.pairs.values
+            when Type::Difference then [type.base]
+            else return false
+            end
+          components.any? { |component| contains_type?(component, &) }
+        end
+
         def accepts_one(self_type, other_type, mode)
           handler = TYPE_HANDLERS[self_type.class]
           return send(handler, self_type, other_type, mode) if handler
@@ -755,10 +810,15 @@ module Rigor
         # `Difference[base, removed]` accepts another type X when the base accepts X *and* X's value set is
         # provably disjoint from `removed`. The disjointness test is the subtle part — it is NOT the same as
         # `removed.accepts(X)`, because `Nominal[String]` includes `""` even though `Constant[""]` does not
-        # "accept" `Nominal[String]`. The conservative rule here: we can prove disjointness only when X is
-        # itself a `Constant` carrier (compare values directly) or another `Difference` with the same
-        # removed value (already exhibits the disjointness). Any other shape — Nominal, Union, IntegerRange
-        # — could overlap the removed value, so the difference rejects it under gradual mode.
+        # "accept" `Nominal[String]`. The conservative rule here: we can prove disjointness only when X is a
+        # carrier whose value set is visibly apart from `removed` — a `Constant` (compare values directly),
+        # another `Difference` with the same removed value (already exhibits the disjointness), an
+        # `IntegerRange` that skips an Integer removed value, a `Tuple` whose fixed arity differs from a
+        # removed `Tuple`, or a `HashShape` with a required key a closed removed `HashShape` cannot hold. The
+        # last three cover the empty witnesses of `non-zero-int`, `non-empty-array[T]` and
+        # `non-empty-hash[K, V]`. Any other carrier — a Nominal above all — is no proof and the difference
+        # rejects it under gradual mode, even where its values happen to exclude `removed`. A Union or
+        # Intersection argument never reaches this rule whole: `accepts` splits it into members first.
         def accepts_difference(self_type, other_type, mode)
           base_result = accepts(self_type.base, other_type, mode: mode)
           return base_result if base_result.no?
@@ -787,9 +847,27 @@ module Rigor
             # Disjointness is monotonic over Intersection: if any member is provably disjoint from
             # `removed`, the meet is too.
             other_type.members.any? { |m| provably_disjoint_from_removed?(m, removed) }
+          when Type::IntegerRange
+            removed.is_a?(Type::Constant) && removed.value.is_a?(Integer) && !other_type.covers?(removed.value)
+          when Type::Tuple
+            # A Tuple's arity is fixed, so it shares no inhabitant with a Tuple of another arity — the
+            # zero-arity witness `non-empty-array[T]` removes included.
+            removed.is_a?(Type::Tuple) && removed.elements.size != other_type.elements.size
+          when Type::HashShape
+            hash_shape_excludes_removed?(other_type, removed)
           end
         end
 
+        # Every inhabitant of `shape` holds each of its required keys, and a closed `removed` shape holds no
+        # key outside its pairs, so one required key `removed` does not list makes the two disjoint. Against
+        # the closed `{}` witness `non-empty-hash[K, V]` removes, that is any required key; an optional key
+        # proves nothing, since the shape is inhabited without it.
+        def hash_shape_excludes_removed?(shape, removed)
+          return false unless removed.is_a?(Type::HashShape) && removed.closed?
+
+          shape.required_keys.any? { |key| !removed.pairs.key?(key) }
+        end
+
         # `Refined[base, predicate]` accepts another type X when the base accepts the *base* of X *and* X is
         # provably contained in the predicate's value set. The base check is delegated to
         # `accepts(self.base, X.base)` so handlers like `accepts_nominal` see Nominal-vs-Nominal and return
@@ -924,11 +1002,15 @@ module Rigor
 
         # HashShape{k1: T1, ...} accepts another HashShape when every required key of self is required on
         # the other side and Ti accepts Ui (depth covariant). Optional keys may be absent on the other side;
-        # when present, their values are checked. A closed self rejects known or possible extra keys. Other
-        # types are rejected; the converse direction (a Nominal accepting a HashShape) is handled by
+        # when present, their values are checked. A closed self rejects known extra keys, and answers at most
+        # `maybe` for an open source: `h = { a: 1 }; h.default = 0` reopens a shape whose key set is still
+        # exactly the literal's. Other types are rejected, except a `Hash` with a gradual arm (see
+        # {#gradual_hash?}); the converse direction (a Nominal accepting a HashShape) is handled by
         # `accepts_nominal` via projection.
         def accepts_hash_shape(self_type, other_type, mode)
           unless other_type.is_a?(Type::HashShape)
+            return gradual_hash_verdict(self_type, other_type, mode) if gradual_hash?(other_type)
+
             return Type::AcceptsResult.no(
               mode: mode,
               reasons: "HashShape does not accept #{other_type.class}"
@@ -939,8 +1021,6 @@ module Rigor
           return hash_shape_no(mode, "HashShape missing required keys: #{missing.inspect}") unless missing.empty?
 
           if self_type.closed?
-            return hash_shape_no(mode, "HashShape closed target rejects open source") if other_type.open?
-
             extra = other_type.pairs.keys - self_type.pairs.keys
             unless extra.empty?
               return hash_shape_no(mode, "HashShape closed target rejects extra keys: #{extra.inspect}")
@@ -948,9 +1028,59 @@ module Rigor
           end
 
           per_entry = hash_shape_entry_results(self_type, other_type, mode)
-          combine_arg_results(per_entry, mode)
+          result = combine_arg_results(per_entry, mode)
+          return result unless result.yes? && self_type.closed? && other_type.open?
+
+          unread_hash_maybe(mode, "HashShape closed target cannot check open source")
+        end
+
+        # A `Hash` nominal — directly or as the base of a `Difference` (`non-empty-hash[K, V]`) — that is raw or
+        # carries a `Dynamic` arm in a type argument. A hash literal with a `**splat` entry carries the arm by
+        # design, `Hash.new` filled key by key reads as the raw `Hash`, and a declared `Hash[Symbol, untyped]`
+        # is the author saying the hash may hold anything (the reading `MutationRejoin#regrowable_carrier?`
+        # gives a declared gradual arm). The runtime value may then hold exactly the record's keys, so a shape
+        # cannot reject it on the arm's account, the way `Hash[K, V]` accepts a raw `Hash` as maybe. A `Hash`
+        # subclass is not read: its entries need not be the record's (`HashWithIndifferentAccess` stores String
+        # keys).
+        def gradual_hash?(type)
+          nominal = type.is_a?(Type::Difference) ? type.base : type
+          nominal.is_a?(Type::Nominal) && nominal.class_name == "Hash" &&
+            (nominal.type_args.empty? || nominal.type_args.any? { |arg| gradual_arm?(arg) })
+        end
+
+        # `maybe`, unless an argument without a gradual arm already rules the record out: a precise `K` that
+        # rejects a required key (`Hash[String, untyped]` never holds `:a`), or a precise `V` none of whose
+        # members a required key's type accepts.
+        def gradual_hash_verdict(self_type, other_type, mode)
+          nominal = other_type.is_a?(Type::Difference) ? other_type.base : other_type
+          key_type, value_type = nominal.type_args
+          missing = unholdable_keys(self_type, key_type, mode)
+          return hash_shape_no(mode, "Hash key type cannot hold required keys: #{missing.inspect}") if missing.any?
+
+          refused = refused_value_keys(self_type, value_type, mode)
+          return hash_shape_no(mode, "Hash value type refused for required keys: #{refused.inspect}") if refused.any?
+
+          unread_hash_maybe(mode, "HashShape cannot check #{other_type.describe(:short)}")
         end
 
+        def unholdable_keys(self_type, key_type, mode)
+          return [] if key_type.nil? || gradual_arm?(key_type)
+
+          self_type.required_keys.select { |key| key_type.accepts(Type::Combinator.constant_of(key), mode: mode).no? }
+        end
+
+        def refused_value_keys(self_type, value_type, mode)
+          return [] if value_type.nil? || gradual_arm?(value_type)
+
+          members = ContentJoin.union_members(value_type)
+          self_type.required_keys.select do |key|
+            formal = self_type.pairs.fetch(key)
+            members.all? { |member| accepts(formal, member, mode: mode).no? }
+          end
+        end
+
+        def gradual_arm?(type) = ContentJoin.union_members(type).any?(Type::Dynamic)
+
         def hash_shape_entry_results(self_type, other_type, mode)
           self_type.pairs.filter_map do |key, formal|
             next unless other_type.pairs.key?(key)