rigortype 0.0.8 → 0.0.9

data/lib/rigor/inference/builtins/random_catalog.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Random` catalog. Singleton — load once, consult during
+      # dispatch.
+      #
+      # The static classifier marks most Random methods `:leaf`
+      # because their C bodies do not call `rb_funcall*` /
+      # `rb_yield` / `rb_check_frozen` directly. Random is the
+      # canonical case where that heuristic under-counts: every
+      # call to `#rand` / `#bytes` / `Random.rand` / `Random.bytes`
+      # advances the receiver's Mersenne-Twister state through a
+      # helper (`rand_random` -> `random_real` / `random_ulong_limited`),
+      # so folding any of them statically is unsound.
+      # `Random.new_seed` and `Random.urandom` are non-deterministic
+      # (different output every call); even though they are
+      # functionally pure they would produce a misleading constant
+      # at fold time. The whole class is conservative-by-default
+      # at the catalog tier; precision flows through the RBS layer.
+      RANDOM_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/random.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Random" => Set[
+            # `rand_random` -> `random_real` / `random_ulong_limited`
+            # advance the MT state on the receiver (instance #rand)
+            # and on `Random::DEFAULT` (singleton .rand). The
+            # classifier misses the indirect mutator.
+            :rand,
+            # `random_bytes` / `random_s_bytes` consume MT output
+            # the same way #rand does — every call mutates the
+            # underlying generator.
+            :bytes,
+            # Non-deterministic: each call produces a fresh seed
+            # via `with_random_seed` reading platform entropy. Folding
+            # to a constant would freeze a value that the runtime
+            # never actually returns twice.
+            :new_seed,
+            # Non-deterministic: reads from platform CSPRNG (e.g.
+            # /dev/urandom). Folding is unsound for the same reason
+            # as `new_seed`.
+            :urandom,
+            # `initialize_copy` is blocklisted by convention so a
+            # hypothetical future `Constant<Random>` carrier
+            # cannot fold an aliasing copy through the catalog.
+            :initialize_copy
+          ]
+        }
+      )
+    end
+  end
+end

data/lib/rigor/inference/builtins/re_catalog.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Regexp` / `MatchData` catalog. Singleton — load once,
+      # consult during dispatch.
+      #
+      # `Init_Regexp` in `references/ruby/re.c` registers BOTH
+      # classes in a single C init block, so the catalog carries
+      # both — `Regexp` (the pattern carrier) plus `MatchData`
+      # (the result-of-match carrier produced by `Regexp#match` /
+      # `String#match` and consulted via `$~`). The catalog wiring
+      # therefore mostly governs:
+      #
+      # 1. The reader surface on each class (`Regexp#source`,
+      #    `Regexp#options`, `Regexp#casefold?`, `MatchData#size`,
+      #    `MatchData#captures`, etc.) — RBS-declared returns are
+      #    preserved through dispatch.
+      # 2. The blocklist below, which keeps methods that touch
+      #    process-global state (the `$~` backref) from being
+      #    folded. Regexp matching is observably stateful:
+      #    `Regexp#=~`, `#===` and `#~` all call `rb_backref_set`
+      #    (writing `$~` and the `$1..$N` / `$&` / `` $` `` / `$'`
+      #    aliases). A constant-fold that dropped those calls
+      #    would silently change the visible state of the program,
+      #    so they MUST decline through to the RBS tier.
+      #
+      # `Regexp.last_match` and `Regexp.timeout` / `Regexp.timeout=`
+      # are class-level (singleton) methods that also touch
+      # process-global state, but the dispatcher's catalog lookup
+      # only consults `:instance` entries today — class-method calls
+      # on a `Singleton` receiver type take the `meta_*` path in
+      # `MethodDispatcher` rather than walking `CATALOG_BY_CLASS` —
+      # so listing them here would be dead code. Their RBS-tier
+      # signatures already widen the answer enough to keep the
+      # behaviour sound; revisit if the dispatcher ever grows a
+      # singleton-aware catalog path.
+      REGEXP_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/re.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Regexp" => Set[
+            # Defensive: aliasing-copy semantics already covered
+            # by the `:mutates_self` classifier, listed here for
+            # symmetry with String / Array / Hash / Range / Set.
+            :initialize_copy,
+            # `=~`, `===`, `~` all run `rb_reg_search` (or call
+            # `rb_backref_set(Qnil)` directly) — every successful
+            # OR failing match writes `$~` and the
+            # `$1..$N` / `$&` / `` $` `` / `$'` aliases. Folding
+            # would discard the visible side effect.
+            :=~,
+            :"===",
+            :~,
+            # `match` is already `:block_dependent` (the C body
+            # yields), but it ALSO writes `$~` regardless of the
+            # block. Listed here so a future extractor that
+            # reclassifies it as `:leaf` (because the yield is
+            # behind a helper) does not silently fold it.
+            :match
+          ],
+          "MatchData" => Set[
+            # Defensive entry mirroring the other catalogs.
+            # `match_init_copy` is already `:leaf` per the
+            # extractor (it copies the regs slot in place but
+            # uses no helper the C-body regex flags as a
+            # mutator); blocked so a future
+            # `Constant<MatchData>` carrier never folds an
+            # aliasing copy through the catalog.
+            :initialize_copy
+          ]
+        }
+      )
+    end
+  end
+end

data/lib/rigor/inference/builtins/struct_catalog.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Struct` catalog. Singleton — load once, consult during
+      # dispatch.
+      #
+      # `Struct` is a meta-class: `Struct.new(*members)` returns a
+      # fresh anonymous subclass — never a `Struct` value. Today
+      # Rigor never produces a `Constant<Struct>` carrier (a literal
+      # struct instance), so the catalog is defensive: it documents
+      # the shape and forbids unsafe folds in case a future tier
+      # learns to lift literal struct instances into the value
+      # lattice.
+      #
+      # Subclasses define their own writers (`name=`) at class-build
+      # time, so per-instance member accessors do not appear in this
+      # YAML — only the generic `[]` / `[]=` pair on the base class.
+      # `[]=` is already classified `:mutates_self`; `[]` reads a
+      # member but the answer depends on the subclass's member
+      # definition, which the catalog does not see, so we blocklist
+      # it defensively.
+      STRUCT_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/struct.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Struct" => Set[
+            # Defensive: aliasing-copy semantics on a hypothetical
+            # `Constant<Struct>` carrier. Convention across the
+            # other catalogs (Range, Random, Pathname).
+            :initialize_copy,
+            # `rb_struct_hash` mixes member values via
+            # `rb_hash` -> `rb_funcall(:hash, ...)`. The classifier
+            # sees no direct dispatch because the recursion goes
+            # through `rb_hash` (a helper), but the answer depends
+            # on the member values' `#hash` — user-redefinable.
+            # Block to avoid folding a hash that would diverge
+            # from the runtime once a member overrides `#hash`.
+            :hash,
+            # `rb_struct_aref` reads a member by name or index; the
+            # answer depends on the subclass's member layout, which
+            # the catalog does not carry. Folding without knowing
+            # the layout would be unsound.
+            :[]
+          ]
+        }
+      )
+    end
+  end
+end

data/lib/rigor/inference/expression_typer.rb

@@ -472,10 +472,35 @@ module Rigor
         [keys, values]
       end
 
-      def type_of_interpolated_string(_node)
+      # An interpolated string `"#{a}b#{c}"` is `literal-string`
+      # when every part contributes literal-bearing material:
+      # plain text segments are literal by construction, embedded
+      # expressions count when their type is itself literal-string-
+      # compatible (a `Constant<String>`, the `literal-string`
+      # carrier, an `Intersection` containing it, or a `Union`
+      # whose members all qualify). Otherwise the result widens to
+      # plain `Nominal[String]` as before.
+      def type_of_interpolated_string(node)
+        return Type::Combinator.literal_string if interpolation_parts_literal?(node.parts)
+
         Type::Combinator.nominal_of(String)
       end
 
+      def interpolation_parts_literal?(parts)
+        parts.all? { |part| interpolation_part_literal?(part) }
+      end
+
+      def interpolation_part_literal?(part)
+        case part
+        when Prism::StringNode
+          true
+        when Prism::EmbeddedStatementsNode, Prism::EmbeddedVariableNode
+          Type::Combinator.literal_string_compatible?(type_of(part))
+        else
+          false
+        end
+      end
+
       def type_of_interpolated_symbol(_node)
         Type::Combinator.nominal_of(Symbol)
       end

data/lib/rigor/inference/method_dispatcher/constant_folding.rb

@@ -14,6 +14,12 @@ require_relative "../builtins/enumerable_catalog"
 require_relative "../builtins/rational_catalog"
 require_relative "../builtins/complex_catalog"
 require_relative "../builtins/pathname_catalog"
+require_relative "../builtins/random_catalog"
+require_relative "../builtins/struct_catalog"
+require_relative "../builtins/encoding_catalog"
+require_relative "../builtins/re_catalog"
+require_relative "../builtins/proc_catalog"
+require_relative "../builtins/exception_catalog"
 
 module Rigor
   module Inference
@@ -1077,7 +1083,16 @@ module Rigor
           [Date,     [Builtins::DATE_CATALOG,   "Date"]],
           [Rational, [Builtins::RATIONAL_CATALOG, "Rational"]],
           [Complex,  [Builtins::COMPLEX_CATALOG,  "Complex"]],
-          [Pathname, [Builtins::PATHNAME_CATALOG, "Pathname"]]
+          [Pathname, [Builtins::PATHNAME_CATALOG, "Pathname"]],
+          [Random, [Builtins::RANDOM_CATALOG, "Random"]],
+          [Struct, [Builtins::STRUCT_CATALOG, "Struct"]],
+          [Encoding, [Builtins::ENCODING_CATALOG, "Encoding"]],
+          [Regexp, [Builtins::REGEXP_CATALOG, "Regexp"]],
+          [MatchData, [Builtins::REGEXP_CATALOG, "MatchData"]],
+          [Proc, [Builtins::PROC_CATALOG, "Proc"]],
+          [Method, [Builtins::PROC_CATALOG, "Method"]],
+          [UnboundMethod, [Builtins::PROC_CATALOG, "UnboundMethod"]],
+          [Exception, [Builtins::EXCEPTION_CATALOG, "Exception"]]
         ].freeze
         private_constant :CATALOG_BY_CLASS
 

data/lib/rigor/inference/method_dispatcher/literal_string_folding.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Dispatcher tier that lifts string-composition results into
+      # the `literal-string` carrier when every operand is itself
+      # literal-bearing. Sits between {ConstantFolding} (which
+      # handles all-Constant cases) and {ShapeDispatch}; runs only
+      # for `String#+` / `String#*` / `String#<<` / `String#concat`
+      # calls whose inputs the ConstantFolding tier could not fold
+      # to a precise `Constant<String>` (e.g. one operand is
+      # `literal-string` rather than `Constant<String>`, or the
+      # multiplication exceeds the constant-fold size cap).
+      #
+      # Result rule:
+      #
+      # - `+`, `<<`, `concat`: receiver and argument MUST both be
+      #   `Type::Combinator.literal_string_compatible?`. The result
+      #   is `literal-string`. `<<` and `concat` mutate the
+      #   receiver at runtime; the analyzer does not track that
+      #   mutation against the local's binding, but the call's
+      #   *return value* is the receiver itself, and the receiver
+      #   stays literal-bearing because every appended slice was
+      #   literal-bearing too.
+      # - `*`: receiver MUST be literal-bearing; argument MUST be
+      #   integer-typed. The result is `literal-string`.
+      #
+      # Other receiver / argument shapes decline so the next tier
+      # (ShapeDispatch / FileFolding / RbsDispatch) takes over and
+      # the call site widens to the RBS-declared `Nominal[String]`
+      # as before.
+      module LiteralStringFolding
+        module_function
+
+        CONCAT_METHODS = %i[+ << concat].freeze
+        private_constant :CONCAT_METHODS
+
+        def try_dispatch(receiver:, method_name:, args:, **)
+          return nil unless Type::Combinator.literal_string_compatible?(receiver)
+          return nil unless args.size == 1
+
+          if CONCAT_METHODS.include?(method_name)
+            fold_concat(args.first)
+          elsif method_name == :*
+            fold_repeat(args.first)
+          end
+        end
+
+        def fold_concat(arg_type)
+          return nil unless Type::Combinator.literal_string_compatible?(arg_type)
+
+          Type::Combinator.literal_string
+        end
+
+        def fold_repeat(arg_type)
+          return nil unless integer_typed?(arg_type)
+          return nil if known_negative_integer?(arg_type)
+
+          Type::Combinator.literal_string
+        end
+
+        def integer_typed?(type)
+          case type
+          when Type::Constant then type.value.is_a?(Integer)
+          when Type::Nominal then type.class_name == "Integer"
+          when Type::IntegerRange then true
+          else false
+          end
+        end
+
+        # `String#*` raises ArgumentError on a negative multiplier, so a
+        # `Constant<-1>` argument is not a valid lift target. Decline so
+        # the call site keeps the existing nil-result behaviour rather
+        # than promising a `literal-string` value that could never
+        # exist at runtime.
+        def known_negative_integer?(type)
+          type.is_a?(Type::Constant) && type.value.is_a?(Integer) && type.value.negative?
+        end
+
+        private_class_method :fold_concat, :fold_repeat, :integer_typed?
+      end
+    end
+  end
+end

data/lib/rigor/inference/method_dispatcher.rb

@@ -3,6 +3,7 @@
 require_relative "../reflection"
 require_relative "../type"
 require_relative "method_dispatcher/constant_folding"
+require_relative "method_dispatcher/literal_string_folding"
 require_relative "method_dispatcher/shape_dispatch"
 require_relative "method_dispatcher/rbs_dispatch"
 require_relative "method_dispatcher/iterator_dispatch"
@@ -101,6 +102,7 @@ module Rigor
         return meta_result if meta_result
 
         ConstantFolding.try_fold(receiver: receiver_type, method_name: method_name, args: arg_types) ||
+          LiteralStringFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
           ShapeDispatch.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
           FileFolding.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||
           KernelDispatch.try_dispatch(receiver: receiver_type, method_name: method_name, args: arg_types) ||

data/lib/rigor/inference/narrowing.rb

@@ -539,26 +539,41 @@ module Rigor
         # downstream narrowing knows the refinement subset is
         # excluded.
         #
-        # The result is sound but imprecise: without a
-        # complementary carrier (e.g. `mixed-case-string` for
-        # `~lowercase-string`) we cannot enumerate the surviving
-        # values. Difference is the carrier-of-last-resort, and
-        # the existing `Type::Difference` consumers already
-        # treat it correctly.
+        # v0.0.9 — when the predicate has a registered
+        # complement (see {Type::Refined::COMPLEMENT_PAIRS}) and
+        # the part is exactly the refinement's base, the
+        # narrowing returns `Refined[base, complement_predicate]`
+        # instead of `Difference[base, refined]`. This is the
+        # `~T` symmetry the spec promises: `~lowercase-string`
+        # narrows `String` to `non-lowercase-string` rather than
+        # `Difference[String, lowercase-string]`.
+        #
+        # Predicates without a registered complement still fall
+        # back to the imprecise but sound `Difference[part,
+        # refined]` carrier so behaviour is unchanged for
+        # untouched call sites.
         def complement_refined(current_type, refined)
-          base = refined.base
+          complement = registered_complement_for(refined)
           parts = current_type.is_a?(Type::Union) ? current_type.members : [current_type]
+          survivors = parts.filter_map { |part| complement_refined_part(part, refined, complement) }
+          return current_type if survivors.empty?
+
+          Type::Combinator.union(*survivors)
+        end
 
-          survivors = parts.map do |part|
-            next nil if part == refined
-            next part if base_disjoint?(base, part)
+        def complement_refined_part(part, refined, complement)
+          return nil if part == refined
+          return part if base_disjoint?(refined.base, part)
+          return complement if complement && part == refined.base
 
-            Type::Combinator.difference(part, refined)
-          end.compact
+          Type::Combinator.difference(part, refined)
+        end
 
-          return current_type if survivors.empty?
+        def registered_complement_for(refined)
+          complement_id = refined.complement_predicate_id
+          return nil if complement_id.nil?
 
-          Type::Combinator.union(*survivors)
+          Type::Combinator.refined(refined.base, complement_id)
         end
 
         def falsey_value?(value)

data/lib/rigor/rbs_extended.rb

@@ -2,6 +2,7 @@
 
 require_relative "type"
 require_relative "builtins/imported_refinements"
+require_relative "flow_contribution"
 
 module Rigor
   # Slice 7 phase 15 — first-preview reader for the
@@ -410,5 +411,59 @@ module Rigor
 
       ParamOverride.new(param_name: match[:param].to_sym, type: type)
     end
+
+    # The shared {Rigor::FlowContribution::Provenance} for every
+    # bundle this module produces. `source_family: :rbs_extended`
+    # so consumers (today the documentation surface; v0.1.0 the
+    # plugin contribution merger) can attribute facts back to the
+    # RBS::Extended layer.
+    RBS_EXTENDED_PROVENANCE = FlowContribution::Provenance.new(
+      source_family: :rbs_extended,
+      plugin_id: nil,
+      node: nil,
+      descriptor: nil
+    ).freeze
+
+    # Rolls up every recognised RBS::Extended directive on
+    # `method_def` into a single {Rigor::FlowContribution}:
+    #
+    # - `predicate-if-true`  → `truthy_facts` (`PredicateEffect`s)
+    # - `predicate-if-false` → `falsey_facts` (`PredicateEffect`s)
+    # - `assert*`            → `post_return_facts` (`AssertEffect`s)
+    # - `return:` override   → `return_type` (`Rigor::Type`)
+    #
+    # Param overrides are intentionally NOT included — they refine
+    # the call's signature contract rather than its flow facts and
+    # do not fit ADR-2 § "Flow Contribution Bundle" slot semantics.
+    # Callers that care about parameter contracts keep using
+    # {.read_param_type_overrides} / {.param_type_override_map}.
+    #
+    # Returns `nil` when the method carries no recognised
+    # contribution directives (callers can skip the merge step
+    # without iterating an empty bundle).
+    def read_flow_contribution(method_def)
+      return nil if method_def.nil?
+
+      predicate_effects = read_predicate_effects(method_def)
+      assert_effects = read_assert_effects(method_def)
+      return_override = read_return_type_override(method_def)
+      return nil if predicate_effects.empty? && assert_effects.empty? && return_override.nil?
+
+      build_flow_contribution(predicate_effects, assert_effects, return_override)
+    end
+
+    def build_flow_contribution(predicate_effects, assert_effects, return_override)
+      FlowContribution.new(
+        return_type: return_override,
+        truthy_facts: nilable_slot(predicate_effects.select(&:truthy_only?)),
+        falsey_facts: nilable_slot(predicate_effects.select(&:falsey_only?)),
+        post_return_facts: nilable_slot(assert_effects),
+        provenance: RBS_EXTENDED_PROVENANCE
+      )
+    end
+
+    def nilable_slot(facts)
+      facts.empty? ? nil : facts
+    end
   end
 end

data/lib/rigor/type/combinator.rb

@@ -149,14 +149,40 @@ module Rigor
         Refined.new(nominal_of("String"), :lowercase)
       end
 
+      # Complement of `lowercase-string`: a `String` with at least
+      # one non-lowercase character (i.e. `v != v.downcase`).
+      # Registered as the paired complement of
+      # `:lowercase` in {Refined::COMPLEMENT_PAIRS} so
+      # `~lowercase-string` narrows to this carrier instead of
+      # falling back to `Difference[String, lowercase-string]`.
+      def non_lowercase_string
+        Refined.new(nominal_of("String"), :not_lowercase)
+      end
+
       def uppercase_string
         Refined.new(nominal_of("String"), :uppercase)
       end
 
+      # Complement of `uppercase-string`: a `String` with at least
+      # one non-uppercase character. Paired with `:uppercase` in
+      # {Refined::COMPLEMENT_PAIRS}.
+      def non_uppercase_string
+        Refined.new(nominal_of("String"), :not_uppercase)
+      end
+
       def numeric_string
         Refined.new(nominal_of("String"), :numeric)
       end
 
+      # Complement of `numeric-string`: a `String` that is not
+      # accepted by Rigor's Ruby numeric-string predicate
+      # (contains at least one non-digit, has a malformed numeric
+      # form, etc.). Paired with `:numeric` in
+      # {Refined::COMPLEMENT_PAIRS}.
+      def non_numeric_string
+        Refined.new(nominal_of("String"), :not_numeric)
+      end
+
       def decimal_int_string
         Refined.new(nominal_of("String"), :decimal_int)
       end
@@ -169,6 +195,52 @@ module Rigor
         Refined.new(nominal_of("String"), :hex_int)
       end
 
+      # `literal-string` — a `String` that is statically known to
+      # come from a source-code literal (or a composition of
+      # literals). v0.0.9 tracks this flow through interpolation
+      # `"#{...}"`, leaving propagation through `+` / `<<` to a
+      # later slice. Every `Constant<String>` is implicitly
+      # literal-string-compatible; the carrier exists for cases
+      # where the concrete value is unknown but literal-ness has
+      # been established (an RBS::Extended `return: literal-string`
+      # annotation, or interpolation over literal-bearing parts).
+      def literal_string
+        Refined.new(nominal_of("String"), :literal_string)
+      end
+
+      # `non-empty-literal-string` = `non-empty-string ∩ literal-string`.
+      # Composes the point-removal half (`Difference[String, ""]`)
+      # with the predicate-subset half. Both members erase to
+      # `String`.
+      def non_empty_literal_string
+        intersection(non_empty_string, literal_string)
+      end
+
+      # Recognises the carriers that participate in literal-string
+      # flow tracking: any `Constant<String>` (constants are literal
+      # by construction), the `literal-string` Refined carrier, an
+      # `Intersection` containing `literal-string`, or a `Union`
+      # whose every member qualifies. Used by
+      # `ExpressionTyper#type_of_interpolated_string` and the
+      # `LiteralStringFolding` dispatcher tier so propagation
+      # through interpolation and `+`/`*` composition stays
+      # consistent.
+      def literal_string_compatible?(type)
+        case type
+        when Constant then type.value.is_a?(String)
+        when Refined then literal_string_carrier?(type)
+        when Intersection then type.members.any? { |m| literal_string_compatible?(m) }
+        when Union then type.members.all? { |m| literal_string_compatible?(m) }
+        else false
+        end
+      end
+
+      def literal_string_carrier?(refined)
+        refined.predicate_id == :literal_string &&
+          refined.base.is_a?(Nominal) &&
+          refined.base.class_name == "String"
+      end
+
       # Normalised intersection. Flattens nested Intersections,
       # drops `Top` members, collapses to `Bot` if any member is
       # `Bot`, deduplicates structurally-equal members, sorts the

data/lib/rigor/type/refined.rb

@@ -141,11 +141,24 @@ module Rigor
 
       PREDICATES = {
         lowercase: ->(v) { v.is_a?(String) && v == v.downcase },
+        not_lowercase: ->(v) { v.is_a?(String) && v != v.downcase },
         uppercase: ->(v) { v.is_a?(String) && v == v.upcase },
+        not_uppercase: ->(v) { v.is_a?(String) && v != v.upcase },
         numeric: ->(v) { v.is_a?(String) && NUMERIC_STRING_PATTERN.match?(v) },
+        not_numeric: ->(v) { v.is_a?(String) && !NUMERIC_STRING_PATTERN.match?(v) },
         decimal_int: ->(v) { v.is_a?(String) && DECIMAL_INT_STRING_PATTERN.match?(v) },
         octal_int: ->(v) { v.is_a?(String) && OCTAL_INT_STRING_PATTERN.match?(v) },
-        hex_int: ->(v) { v.is_a?(String) && HEX_INT_STRING_PATTERN.match?(v) }
+        hex_int: ->(v) { v.is_a?(String) && HEX_INT_STRING_PATTERN.match?(v) },
+        # `literal-string` is a flow-tracked predicate, not a value-
+        # level predicate: a String is literal-string when it is
+        # known to come from a source-code literal (or composition
+        # of literals). Every concrete `Constant<String>` is
+        # already literal by construction, so the inspection
+        # recogniser returns true for any String — the property is
+        # really tracked in the flow analysis (interpolation,
+        # concatenation, RBS::Extended `return: literal-string`)
+        # rather than recovered by inspecting an arbitrary string.
+        literal_string: ->(v) { v.is_a?(String) }
       }.freeze
 
       # Maps `[base_class_name, predicate_id]` pairs to their
@@ -154,14 +167,49 @@ module Rigor
       # to the operator form.
       CANONICAL_NAMES = {
         ["String", :lowercase] => "lowercase-string",
+        ["String", :not_lowercase] => "non-lowercase-string",
         ["String", :uppercase] => "uppercase-string",
+        ["String", :not_uppercase] => "non-uppercase-string",
         ["String", :numeric] => "numeric-string",
+        ["String", :not_numeric] => "non-numeric-string",
         ["String", :decimal_int] => "decimal-int-string",
         ["String", :octal_int] => "octal-int-string",
-        ["String", :hex_int] => "hex-int-string"
+        ["String", :hex_int] => "hex-int-string",
+        ["String", :literal_string] => "literal-string"
       }.freeze
       private_constant :CANONICAL_NAMES
 
+      # Bidirectional `predicate_id ↔ complement_predicate_id`
+      # registry. `~Refined[base, p]` narrows to
+      # `Refined[base, COMPLEMENT_PAIRS[p]]` when the part is the
+      # refinement's base — the precise carrier the spec promises
+      # under the `~T` operator. Predicates without a registered
+      # complement fall back to the imprecise but sound
+      # `Difference[part, refined]` carrier from the existing
+      # narrowing rule.
+      #
+      # Adding a new pair here is an additive change: register the
+      # complement predicate in {PREDICATES}, give it a kebab-case
+      # canonical name in {CANONICAL_NAMES}, and add the bidirectional
+      # entry below. No call site needs to know about the new pair —
+      # `complement_refined` consults this map and routes through
+      # the registered complement automatically.
+      COMPLEMENT_PAIRS = {
+        lowercase: :not_lowercase,
+        not_lowercase: :lowercase,
+        uppercase: :not_uppercase,
+        not_uppercase: :uppercase,
+        numeric: :not_numeric,
+        not_numeric: :numeric
+      }.freeze
+      private_constant :COMPLEMENT_PAIRS
+
+      # @return [Symbol, nil] the registered complement predicate
+      #   id, or nil when no pair is registered for this predicate.
+      def complement_predicate_id
+        COMPLEMENT_PAIRS[predicate_id]
+      end
+
       private
 
       def canonical_name

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 end