rigortype 0.1.5 → 0.1.7

data/lib/rigor/environment.rb

@@ -3,11 +3,16 @@
 require_relative "environment/class_registry"
 require_relative "environment/rbs_loader"
 require_relative "environment/reflection"
+require_relative "environment/reporters"
+require_relative "environment/hkt_registry_holder"
 require_relative "environment/bundle_sig_discovery"
 require_relative "environment/lockfile_resolver"
 require_relative "environment/rbs_collection_discovery"
 require_relative "environment/rbs_coverage_report"
 require_relative "inference/synthetic_method_index"
+require_relative "inference/project_patched_methods"
+require_relative "inference/hkt_registry"
+require_relative "builtins/hkt_builtins"
 require_relative "type_node/name_scope"
 require_relative "type_node/resolver_chain"
 
@@ -57,8 +62,8 @@ module Rigor
     ].freeze
 
     attr_reader :class_registry, :rbs_loader, :plugin_registry, :dependency_source_index,
-                :rbs_extended_reporter, :boundary_cross_reporter, :name_scope,
-                :synthetic_method_index
+                :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
@@ -79,24 +84,105 @@ module Rigor
     #   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,
+    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil, # rubocop:disable Metrics/ParameterLists
                    plugin_registry: nil, dependency_source_index: nil,
                    rbs_extended_reporter: nil, boundary_cross_reporter: nil,
-                   synthetic_method_index: nil)
+                   synthetic_method_index: nil, project_patched_methods: nil,
+                   hkt_registry: nil)
       @class_registry = class_registry
       @rbs_loader = rbs_loader
       @plugin_registry = plugin_registry
       @dependency_source_index = dependency_source_index
-      @rbs_extended_reporter = rbs_extended_reporter
-      @boundary_cross_reporter = boundary_cross_reporter
+      # ADR-pending — reporters live in a mutable container so
+      # long-lived integrations (LSP `ProjectContext`) can swap
+      # them per `Runner.run` without rebuilding the env. The
+      # existing `#rbs_extended_reporter` / `#boundary_cross_reporter`
+      # accessors below preserve the public lookup shape.
+      @reporters = Reporters.new(
+        rbs_extended: rbs_extended_reporter,
+        boundary_cross: boundary_cross_reporter
+      )
       @synthetic_method_index = synthetic_method_index || Inference::SyntheticMethodIndex::EMPTY
+      @project_patched_methods = project_patched_methods || Inference::ProjectPatchedMethods::EMPTY
+      # ADR-20 slice 2c + 2e — the per-env HKT registry
+      # consulted by the reducer when resolving `Type::App`
+      # carriers. Defaults to {Inference::HktRegistry::EMPTY};
+      # the {.default} / {.for_project} class methods seed it
+      # with the bundled builtins (`json::value`, …) plus any
+      # `%a{rigor:v1:hkt_register / hkt_define}` annotations
+      # the RBS loader exposes. The hkt_registry getter
+      # (defined below) MEMOIZES the result of merging the
+      # base with the RBS scan so the scan is paid at most
+      # once per Environment lifetime — and only when first
+      # consulted, leaving fast paths like `rigor check
+      # --cache-stats --no-stats` from doing the RBS env
+      # build at all.
+      @hkt_registry_base = hkt_registry || Inference::HktRegistry::EMPTY
+      @hkt_registry_holder = HktRegistryHolder.new
       @name_scope = build_name_scope
       freeze
     end
 
+    # ADR-20 slices 2e + 6 — lazy HKT registry getter.
+    # Merge order on first call: builtins (base) ← plugin
+    # manifest aggregation ← RBS env scan. Last-write-wins on
+    # URI collisions so user-authored `.rbs` overlays beat
+    # plugin entries, which beat the bundled JSON_VALUE.
+    # Memoised; single-threaded use only (under the Ractor
+    # pool path each worker has its own Environment so
+    # cross-worker mutation is impossible; the LSP
+    # single-publish-at-a-time invariant serialises here).
+    def hkt_registry
+      @hkt_registry_holder.fetch do
+        with_plugin_overlay = if @plugin_registry.respond_to?(:hkt_overlay_registry)
+                                @hkt_registry_base.merge(@plugin_registry.hkt_overlay_registry)
+                              else
+                                @hkt_registry_base
+                              end
+        Inference::HktRegistry.scan_rbs_loader(
+          @rbs_loader,
+          base: with_plugin_overlay,
+          reporter: rbs_extended_reporter
+        )
+      end
+    end
+
+    # Backwards-compatible reporter accessors — every existing
+    # consumer (rbs_extended, method_dispatcher) calls these. The
+    # frozen `@reporters` container is mutable for slot reassignment
+    # via {#attach_reporters!} below.
+    def rbs_extended_reporter
+      @reporters.rbs_extended
+    end
+
+    def boundary_cross_reporter
+      @reporters.boundary_cross
+    end
+
+    # Replaces the env's per-run reporter slots. Intended for
+    # long-lived integrations (LSP `ProjectContext`) that share one
+    # Environment instance across many `Runner.run` calls: each call
+    # attaches its own fresh reporter pair so per-call diagnostic
+    # events stay scoped to that call rather than accumulating
+    # across publishes.
+    #
+    # Single-threaded use only. Concurrent publishes against one
+    # Environment must serialise — the LSP `Server` debouncer +
+    # synchronized writer already enforces this for the editor
+    # path. The Ractor pool path builds a per-worker Environment
+    # and does not reach this surface.
+    def attach_reporters!(rbs_extended_reporter:, boundary_cross_reporter:)
+      @reporters.rbs_extended = rbs_extended_reporter
+      @reporters.boundary_cross = boundary_cross_reporter
+      nil
+    end
+
     class << self
       def default
-        @default ||= new(rbs_loader: RbsLoader.default).freeze
+        @default ||= new(
+          rbs_loader: RbsLoader.default,
+          hkt_registry: Builtins::HktBuiltins.registry
+        ).freeze
       end
 
       # Builds an Environment that consults the project's local
@@ -127,7 +213,7 @@ module Rigor
                       bundler_bundle_path: nil, bundler_auto_detect: false,
                       bundler_lockfile: nil,
                       rbs_collection_lockfile: nil, rbs_collection_auto_detect: false,
-                      synthetic_method_index: nil)
+                      synthetic_method_index: nil, project_patched_methods: 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
@@ -173,13 +259,24 @@ module Rigor
           signature_paths: loader_signature_paths,
           cache_store: cache_store
         )
+        # 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 up front. URI
+        # collisions let the user-authored overlay win over
+        # the bundled builtin (last-write-wins per ADR-20
+        # OQ3 tentative).
         new(
           rbs_loader: loader,
           plugin_registry: plugin_registry,
           dependency_source_index: dependency_source_index,
           rbs_extended_reporter: rbs_extended_reporter,
           boundary_cross_reporter: boundary_cross_reporter,
-          synthetic_method_index: synthetic_method_index
+          synthetic_method_index: synthetic_method_index,
+          project_patched_methods: project_patched_methods,
+          hkt_registry: Builtins::HktBuiltins.registry
         )
       end
       # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
@@ -257,6 +354,19 @@ module Rigor
       @rbs_loader&.reflection
     end
 
+    # Returns true when the RBS environment carries the named
+    # declaration as a Module (not a Class). Used by the
+    # `user_class_fallback_receiver` tier to detect a module-mixin
+    # receiver (e.g. `PP::ObjectMixin`) so the dispatcher can route
+    # unresolved method calls through the `Nominal[Object]`
+    # fallback — every concrete includer of M honours Kernel /
+    # Object instance methods through its own ancestor chain.
+    def rbs_module?(name)
+      return false unless rbs_loader
+
+      rbs_loader.rbs_module?(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

data/lib/rigor/flow_contribution/fact.rb

@@ -31,14 +31,20 @@ module Rigor
     #
     # ## Field set
     #
-    # - `target_kind`: `:parameter` (call-site argument) or
-    #   `:self` (receiver). Future slices may extend the set
-    #   (`:local`, `:ivar`, `:result`); the merger is agnostic
-    #   to the concrete kinds and only requires equality.
+    # - `target_kind`: `:parameter` (call-site argument), `:self`
+    #   (receiver), or `:local` (a named local in the surrounding
+    #   scope). v0.1.8 Pillar 2 Slice 1 added `:local` so plugins
+    #   recognising bespoke call shapes (`expect(x).to be_a(T)`)
+    #   can narrow a specific scope-bound local without routing
+    #   through the parameter-name lookup that requires an
+    #   authoritative RBS sig on the called method. Future slices
+    #   may extend further (`:ivar`, `:result`). The merger is
+    #   agnostic to the concrete kinds and only requires equality.
     # - `target_name`: a `Symbol`. For `:parameter` it's the
     #   declared parameter name. For `:self` it is the literal
     #   `:self` symbol so the field stays non-nil and the merge
-    #   key is well-defined.
+    #   key is well-defined. For `:local` it's the local-variable
+    #   name (e.g. `:x` for `expect(x).to be_a(T)`).
     # - `type`: a `Rigor::Type::*` (Nominal, Refined,
     #   IntegerRange, Difference, …) the fact narrows the
     #   target toward (when `negative` is false) or away from
@@ -53,7 +59,7 @@ module Rigor
     # value {Element#target} keys on, so two facts that narrow
     # the same parameter from different contribution sources
     # land in the same merge bucket.
-    FACT_VALID_TARGET_KINDS = %i[parameter self].freeze
+    FACT_VALID_TARGET_KINDS = %i[parameter self local].freeze
 
     class Fact < Data.define(:target_kind, :target_name, :type, :negative)
       def initialize(target_kind:, target_name:, type:, negative: false)
@@ -72,10 +78,14 @@ module Rigor
       end
 
       # Composite target identifier the merger keys on. `:self`
-      # for self-targeted facts; otherwise `[:parameter, name]`
-      # so two contributions that narrow the same parameter
-      # (regardless of source family) land in the same merge
-      # bucket.
+      # for self-targeted facts; otherwise `[kind, name]` so two
+      # contributions that narrow the same `(kind, name)` pair —
+      # regardless of source family — land in the same merge
+      # bucket. `:local` and `:parameter` facts that name the
+      # same symbol stay in separate buckets, which is the
+      # correct semantics: a `:local` fact narrows the surrounding
+      # scope's named local, a `:parameter` fact narrows the
+      # call-site argument matching the parameter declaration.
       def target
         target_kind == :self ? :self : [target_kind, target_name]
       end

data/lib/rigor/inference/acceptance.rb

@@ -446,13 +446,45 @@ module Rigor
 
         def accepts_nominal_from_constant(self_type, constant, mode)
           ruby_class = resolve_class(self_type.class_name)
-          if ruby_class.nil?
-            return Type::AcceptsResult.maybe(
+          return constant_is_a_result(ruby_class, constant, self_type, mode) if ruby_class
+
+          # The host process may not have required the constant's
+          # declared self_type (e.g. `BigDecimal` since Ruby 3.4
+          # is no longer a default gem). Fall back to inspecting
+          # the value's own class ancestor chain — always loadable
+          # because the value already exists. Required for
+          # OverloadSelector to reject `Integer#+(BigDecimal) ->
+          # BigDecimal` overloads contributed by `bigdecimal`'s
+          # RBS reopening when the actual arg is a Constant<Integer>.
+          ancestor_names = constant.value.class.ancestors.map(&:name)
+          if ancestor_names.include?(self_type.class_name)
+            Type::AcceptsResult.yes(
               mode: mode,
-              reasons: "class #{self_type.class_name} not loadable; cannot prove from Constant"
+              reasons: "Constant value class ancestors include #{self_type.class_name}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Constant value class ancestors exclude #{self_type.class_name}"
             )
           end
+        end
+
+        def subtype_result_via_ancestors(actual_class, target_name, mode)
+          if actual_class.ancestors.map(&:name).include?(target_name)
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "#{actual_class.name} ancestors include #{target_name}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "#{actual_class.name} ancestors exclude #{target_name} (target unloadable)"
+            )
+          end
+        end
 
+        def constant_is_a_result(ruby_class, constant, self_type, mode)
           if constant.value.is_a?(ruby_class)
             Type::AcceptsResult.yes(mode: mode, reasons: "Constant value is_a?(#{self_type.class_name})")
           else
@@ -794,6 +826,19 @@ module Rigor
 
           target_class = resolve_class(target_name)
           actual_class = resolve_class(actual_name)
+          # When only `actual` resolves, we can still rule out
+          # `actual <:= target` by inspecting `actual`'s ancestor
+          # chain. The canonical case: `target=BigDecimal` is not
+          # loadable in the host process (no `require` in rigor's
+          # own runtime), but `actual=Integer` IS, and Integer's
+          # ancestors do not include `BigDecimal`, so the subtype
+          # relation MUST be `:no` rather than the conservative
+          # `:maybe`. The reverse asymmetry (target resolves,
+          # actual doesn't) does not let us conclude anything —
+          # the unloaded `actual` could be an unrelated class or
+          # a subclass of `target` we can't see, so we still
+          # answer `:maybe` there.
+          return subtype_result_via_ancestors(actual_class, target_name, mode) if target_class.nil? && actual_class
           if target_class.nil? || actual_class.nil?
             return Type::AcceptsResult.maybe(
               mode: mode,

data/lib/rigor/inference/expression_typer.rb

@@ -61,6 +61,10 @@ module Rigor
         Prism::RationalNode => :type_of_literal_value,
         Prism::SymbolNode => :symbol_type_for,
         Prism::StringNode => :string_type_for,
+        Prism::XStringNode => :type_of_xstring,
+        Prism::InterpolatedXStringNode => :type_of_xstring,
+        Prism::SourceFileNode => :type_of_source_file,
+        Prism::SourceLineNode => :type_of_source_line,
         Prism::TrueNode => :type_of_true,
         Prism::FalseNode => :type_of_false,
         Prism::NilNode => :type_of_nil,
@@ -144,6 +148,9 @@ module Rigor
         Prism::AliasMethodNode => :type_of_nil_value,
         Prism::AliasGlobalVariableNode => :type_of_nil_value,
         Prism::UndefNode => :type_of_nil_value,
+        Prism::PostExecutionNode => :type_of_nil_value,
+        Prism::ShareableConstantNode => :type_of_shareable_constant,
+        Prism::ImplicitNode => :type_of_implicit,
         Prism::ForwardingSuperNode => :type_of_dynamic_top,
         Prism::BlockArgumentNode => :type_of_non_value,
         # Parameters and blocks (non-value positions)
@@ -159,6 +166,7 @@ module Rigor
         Prism::ForwardingParameterNode => :type_of_non_value,
         Prism::NoKeywordsParameterNode => :type_of_non_value,
         Prism::ImplicitRestNode => :type_of_non_value,
+        Prism::ItParametersNode => :type_of_non_value,
         Prism::BlockNode => :type_of_dynamic_top,
         Prism::SplatNode => :type_of_non_value,
         # Control flow (Slice 3 phase 1): branch types are unioned, jumps
@@ -188,8 +196,8 @@ module Rigor
         Prism::UntilNode => :type_of_loop,
         Prism::ForNode => :type_of_dynamic_top,
         Prism::DefinedNode => :type_of_defined,
-        Prism::NumberedReferenceReadNode => :type_of_string_or_nil,
-        Prism::BackReferenceReadNode => :type_of_string_or_nil,
+        Prism::NumberedReferenceReadNode => :type_of_numbered_reference,
+        Prism::BackReferenceReadNode => :type_of_back_reference,
         Prism::MatchPredicateNode => :type_of_match_predicate,
         Prism::MatchRequiredNode => :type_of_match_required,
         Prism::MatchWriteNode => :type_of_dynamic_top,
@@ -339,6 +347,21 @@ module Rigor
         )
       end
 
+      # `$1` / `$2` / ... — numbered match-data globals. When the
+      # narrowing tier has bound a tighter type for this number
+      # (typically `String` after a `=~`-success guard like `unless
+      # /(\d+)/ =~ s; raise; end`), prefer the scope-bound type.
+      # Falls back to the default `String | nil`.
+      def type_of_numbered_reference(node)
+        scope.global(:"$#{node.number}") || type_of_string_or_nil(node)
+      end
+
+      # `$&` / `$'` / `$\`` / `$+` — symbolic back-references. Same
+      # narrowing model as numbered references.
+      def type_of_back_reference(node)
+        scope.global(node.name) || type_of_string_or_nil(node)
+      end
+
       # `expr in pattern` — pattern-match predicate. Returns `true`
       # when the pattern matches, `false` otherwise.
       def type_of_match_predicate(_node)
@@ -888,6 +911,45 @@ module Rigor
         Type::Combinator.constant_of(unescaped)
       end
 
+      # Backtick (`cmd`) and `%x{cmd}` invoke Kernel#` and always return a
+      # String. Even when the content is statically known, we widen to
+      # Nominal[String] because the runtime value depends on the
+      # subprocess output, not the source text.
+      def type_of_xstring(_node)
+        Type::Combinator.nominal_of(String)
+      end
+
+      # __FILE__ is the source file path. Always non-empty when
+      # parsing a real file (the path resolver gives the buffer
+      # name, which is at minimum `"(stdin)"` / `"-e"` / a real
+      # path — never the empty String). Widened to
+      # `non-empty-string` instead of `Nominal[String]` so
+      # downstream String-emptiness checks know the value cannot
+      # be `""`.
+      def type_of_source_file(_node)
+        Type::Combinator.non_empty_string
+      end
+
+      # __LINE__ is the line of the source literal. Ruby line
+      # numbers are 1-indexed, so `__LINE__` is always at least
+      # 1 — `positive-int` (Integer in `[1, +Inf)`) is the
+      # canonical refinement.
+      def type_of_source_line(_node)
+        Type::Combinator.positive_int
+      end
+
+      # `# shareable_constant_value:` magic comment wraps the next
+      # constant write. Type is the wrapped write's value.
+      def type_of_shareable_constant(node)
+        type_of(node.write)
+      end
+
+      # `{ x: }` shorthand hash. The implicit value is the call to
+      # `x` (or a local read of `x`). Delegate.
+      def type_of_implicit(node)
+        type_of(node.value)
+      end
+
       def local_read(node)
         scope.local(node.name) || dynamic_top
       end

data/lib/rigor/inference/hkt_body.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-20 Slice 2a — node types for the parsed body of a
+    # type-function `Definition`. Each node represents one
+    # piece of a Rigor-side type expression that the reducer
+    # ({HktReducer}) walks against a concrete argument list.
+    #
+    # Slice 2a ships a programmatic constructor surface only:
+    # plugin and Rigor-bundled overlay authors build a body
+    # tree by hand using these node types. The string-grammar
+    # parser that reads `Definition#body` (the raw String slot
+    # already populated by Slice 1's `HktDirectives.parse_define`)
+    # into a tree is Slice 2b's deliverable; until it ships, the
+    # `body` String stays opaque and `body_tree` is the
+    # evaluable form.
+    #
+    # The five node types cover the JSON.parse and dry-monads
+    # use cases ADR-20 § Implementation slicing names as
+    # near-term adopters:
+    #
+    # - {TypeLeaf}    — wraps a fully-built `Rigor::Type`
+    #   (use for atoms like `nil`, `Constant<true>`,
+    #   `Nominal[Integer]`).
+    # - {Param}       — reference to a formal parameter
+    #   declared in the enclosing `Definition#params` list
+    #   (e.g. `K` in `json::value[K]`). The reducer
+    #   substitutes from the application's `args`.
+    # - {AppRef}      — abstract HKT application; the reducer
+    #   resolves it via the registry, or returns the `App`
+    #   carrier as-is when the reference is self-recursive
+    #   (lazy "tying-the-knot" handling that lets recursive
+    #   sums like `json::value` reduce without infinite
+    #   expansion).
+    # - {Union}       — N-ary union of arms.
+    # - {NominalApp}  — parameterised nominal class
+    #   (`Array[X]`, `Hash[K, V]`) whose type args are
+    #   themselves body nodes.
+    #
+    # Every node is a frozen `Data.define` value; structural
+    # equality is by-field.
+    module HktBody
+      # Wraps a pre-built `Rigor::Type` value. Use for atoms
+      # that need no substitution (e.g. `Nominal[Integer]`,
+      # `Constant<nil>`).
+      TypeLeaf = Data.define(:type) do
+        def initialize(type:)
+          raise ArgumentError, "type must not be nil" if type.nil?
+
+          super
+        end
+      end
+
+      # Reference to a formal parameter the enclosing
+      # `Definition#params` declared. The reducer substitutes
+      # this node with the matching positional arg from the
+      # `App` being reduced; an unknown name raises during
+      # reduction (the parser, when it ships, MUST reject
+      # unknown names earlier).
+      Param = Data.define(:name) do
+        def initialize(name:)
+          raise ArgumentError, "name must be a Symbol, got #{name.class}" unless name.is_a?(Symbol)
+
+          super
+        end
+      end
+
+      # Abstract HKT application — the reducer's primary
+      # recursion point. `uri` is a namespaced Symbol
+      # matching some `Registration` in the registry; `args`
+      # is an Array of body nodes (each gets substituted /
+      # resolved before being used).
+      AppRef = Data.define(:uri, :args) do
+        def initialize(uri:, args:)
+          raise ArgumentError, "uri must be a Symbol, got #{uri.class}" unless uri.is_a?(Symbol)
+          raise ArgumentError, "uri must be namespaced as `:a::b`, got #{uri.inspect}" unless uri.to_s.include?("::")
+          raise ArgumentError, "args must be an Array, got #{args.class}" unless args.is_a?(Array)
+          raise ArgumentError, "args must be non-empty" if args.empty?
+
+          super(uri: uri, args: args.dup.freeze)
+        end
+      end
+
+      # N-ary union. The reducer builds the result through
+      # `Type::Combinator.union(*reduced_arms)` so
+      # normalization (flattening, dedup, Bot drop) applies.
+      Union = Data.define(:arms) do
+        def initialize(arms:)
+          raise ArgumentError, "arms must be an Array, got #{arms.class}" unless arms.is_a?(Array)
+          raise ArgumentError, "arms must be non-empty" if arms.empty?
+
+          super(arms: arms.dup.freeze)
+        end
+      end
+
+      # Parameterised nominal class. `class_name` is the
+      # Ruby class name (`"Array"`, `"Hash"`); `args` is an
+      # Array of body nodes for the type arguments. The
+      # reducer builds the result through
+      # `Type::Combinator.nominal_of(class_name, type_args:
+      # reduced_args)`.
+      NominalApp = Data.define(:class_name, :args) do
+        def initialize(class_name:, args:)
+          unless class_name.is_a?(String) && !class_name.empty?
+            raise ArgumentError, "class_name must be a non-empty String, got #{class_name.inspect}"
+          end
+          raise ArgumentError, "args must be an Array, got #{args.class}" unless args.is_a?(Array)
+          raise ArgumentError, "args must be non-empty (use TypeLeaf with Nominal for raw class refs)" if args.empty?
+
+          super(class_name: class_name, args: args.dup.freeze)
+        end
+      end
+
+      # ADR-20 § D3 — conditional type form. `test` is a
+      # {TestSubtype} / {TestEquality} / {TestMembership}
+      # value object the reducer evaluates against the
+      # current bindings; `then_branch` / `else_branch` are
+      # body nodes. The reducer's trinary handling:
+      #
+      # - test = `yes` → return the reduced `then_branch`.
+      # - test = `no` → return the reduced `else_branch`.
+      # - test = `maybe` → widen to the union of both
+      #   reduced branches (per ADR-20 WD7 / robustness
+      #   principle).
+      Conditional = Data.define(:test, :then_branch, :else_branch) do
+        def initialize(test:, then_branch:, else_branch:)
+          raise ArgumentError, "test must not be nil" if test.nil?
+          raise ArgumentError, "then_branch must not be nil" if then_branch.nil?
+          raise ArgumentError, "else_branch must not be nil" if else_branch.nil?
+
+          super
+        end
+      end
+
+      # `left <: right` — subtype check. `left` is typically
+      # a {Param} reference; `right` is any body expression.
+      TestSubtype = Data.define(:left, :right) do
+        def initialize(left:, right:)
+          raise ArgumentError, "left/right must not be nil" if left.nil? || right.nil?
+
+          super
+        end
+      end
+
+      # `left == right` — structural equality. Useful for
+      # discriminating against literal constants
+      # (`E == :symbol`).
+      TestEquality = Data.define(:left, :right) do
+        def initialize(left:, right:)
+          raise ArgumentError, "left/right must not be nil" if left.nil? || right.nil?
+
+          super
+        end
+      end
+
+      # `left in [opt1, opt2, ...]` — set membership. Each
+      # `option` is a body node; the test passes iff `left`
+      # is structurally equal to any of the options.
+      TestMembership = Data.define(:left, :options) do
+        def initialize(left:, options:)
+          raise ArgumentError, "left must not be nil" if left.nil?
+          raise ArgumentError, "options must be an Array, got #{options.class}" unless options.is_a?(Array)
+          raise ArgumentError, "options must be non-empty" if options.empty?
+
+          super(left: left, options: options.dup.freeze)
+        end
+      end
+    end
+  end
+end