rigortype 0.0.8 → 0.1.0

data/lib/rigor/environment/rbs_loader.rb

@@ -42,9 +42,29 @@ module Rigor
         def reset_default!
           @default = nil
         end
+
+        # Builds an `RBS::Environment` from explicit `libraries` and
+        # `signature_paths`. Stateless surface so the v0.0.9
+        # {Cache::RbsEnvironment} producer can build an env on cache
+        # miss without holding a loader instance, and the
+        # instance-side {#build_env} delegates here so the
+        # implementation stays single-rooted.
+        def build_env_for(libraries:, signature_paths:)
+          rbs_loader = RBS::EnvironmentLoader.new
+          libraries.each do |library|
+            next unless rbs_loader.has_library?(library: library, version: nil)
+
+            rbs_loader.add(library: library, version: nil)
+          end
+          signature_paths.each do |path|
+            path = Pathname(path) unless path.is_a?(Pathname)
+            rbs_loader.add(path: path) if path.directory?
+          end
+          RBS::Environment.from_loader(rbs_loader).resolve_type_names
+        end
       end
 
-      attr_reader :libraries, :signature_paths
+      attr_reader :libraries, :signature_paths, :cache_store
 
       # @param libraries [Array<String, Symbol>] stdlib library names to
       #   load on top of core (e.g., `["pathname", "json"]`). Empty by
@@ -57,9 +77,16 @@ module Rigor
       #   `sig/` tree). Non-existent or non-directory paths are filtered
       #   out at build time so the loader stays robust to fixtures and
       #   bare repositories.
-      def initialize(libraries: [], signature_paths: [])
+      # @param cache_store [Rigor::Cache::Store, nil] the persistent
+      #   cache the loader consults for translated constant lookups
+      #   (and, in later v0.0.9 slices, other Marshal-clean
+      #   reflection artefacts). Pass `nil` (the default) to skip
+      #   the cache entirely; the runner threads its own Store
+      #   through here when caching is enabled.
+      def initialize(libraries: [], signature_paths: [], cache_store: nil)
         @libraries = libraries.map(&:to_s).freeze
         @signature_paths = signature_paths.map { |p| Pathname(p) }.freeze
+        @cache_store = cache_store
         @state = { env: nil, builder: nil }
         @instance_definition_cache = {}
         @singleton_definition_cache = {}
@@ -71,22 +98,69 @@ module Rigor
       # name is loaded. Accepts unprefixed or top-level-prefixed names
       # ("Integer" or "::Integer"). Memoized per-name (positive and
       # negative results both cache).
+      #
+      # When `cache_store` is set, the loader fetches the entire set of
+      # known class / module / alias names once (per process) through
+      # {Cache::RbsKnownClassNames.fetch} and answers `class_known?`
+      # from the in-memory Set. Cold runs pay a single env walk and
+      # persist the result; warm runs (and a separate loader sharing
+      # the same Store) skip the env walk entirely.
       def class_known?(name)
         key = name.to_s
         return @class_known_cache[key] if @class_known_cache.key?(key)
 
-        @class_known_cache[key] = compute_class_known(name)
+        @class_known_cache[key] = if cache_store
+                                    cached_class_known(name)
+                                  else
+                                    compute_class_known(name)
+                                  end
+      end
+
+      # Yields every known class / module / alias name (top-level
+      # prefixed) currently loaded into the environment. The cache
+      # producer that materialises the known-name set uses this so
+      # it never recurses back through {#class_known?}.
+      def each_known_class_name
+        return enum_for(:each_known_class_name) unless block_given?
+
+        env.class_decls.each_key { |rbs_name| yield rbs_name.to_s }
+        env.class_alias_decls.each_key { |rbs_name| yield rbs_name.to_s }
+      rescue ::RBS::BaseError
+        # fail-soft: a broken RBS environment yields no names.
+        # Analyzer-internal errors (NameError, NoMethodError,
+        # LoadError) are NOT swallowed — those are bugs and
+        # must surface so they don't hide silently the way the
+        # v0.0.9 cache `Cache::Descriptor` regression did.
       end
 
       # @return [RBS::Definition, nil] the resolved instance definition
       #   for `class_name`, or nil when the class is unknown or its
       #   definition cannot be built (RBS may raise on broken hierarchies;
       #   we fail-soft and return nil so the caller can fall back).
+      #
+      # When `cache_store` is set, the loader fetches the per-class
+      # definition through {Cache::RbsInstanceDefinitions.fetch} so
+      # subsequent runs (and other loaders sharing the same Store)
+      # skip the `RBS::DefinitionBuilder.build_instance` step.
+      # In-memory `@instance_definition_cache` keeps the per-process
+      # short-circuit on top.
       def instance_definition(class_name)
         key = class_name.to_s
         return @instance_definition_cache[key] if @instance_definition_cache.key?(key)
 
-        @instance_definition_cache[key] = build_instance_definition(class_name)
+        @instance_definition_cache[key] = if cache_store
+                                            cached_instance_definition(class_name)
+                                          else
+                                            build_instance_definition(class_name)
+                                          end
+      end
+
+      # Public uncached accessor used by the cache producer
+      # ({Rigor::Cache::RbsInstanceDefinitions}). Avoids the
+      # `private_method_called` round-trip a `loader.send(...)`
+      # callsite would require.
+      def uncached_instance_definition(class_name)
+        build_instance_definition(class_name)
       end
 
       # @return [RBS::Definition::Method, nil]
@@ -102,11 +176,25 @@ module Rigor
       #   definition are the *class methods* of `class_name`, including
       #   those inherited from `Class` and `Module` for class types.
       #   Returns nil for unknown names and on RBS build errors (fail-soft).
+      #
+      # When `cache_store` is set, the loader fetches the per-class
+      # singleton definition through
+      # {Cache::RbsSingletonDefinitions.fetch}; the same caching
+      # discipline as {#instance_definition}.
       def singleton_definition(class_name)
         key = class_name.to_s
         return @singleton_definition_cache[key] if @singleton_definition_cache.key?(key)
 
-        @singleton_definition_cache[key] = build_singleton_definition(class_name)
+        @singleton_definition_cache[key] = if cache_store
+                                             cached_singleton_definition(class_name)
+                                           else
+                                             build_singleton_definition(class_name)
+                                           end
+      end
+
+      # Public uncached accessor used by the cache producer.
+      def uncached_singleton_definition(class_name)
+        build_singleton_definition(class_name)
       end
 
       # @return [RBS::Definition::Method, nil] the class method on
@@ -133,7 +221,19 @@ module Rigor
       # names (the loader stays fail-soft). NOTE: in the `rbs` gem,
       # `RBS::Definition#type_params` returns `Array<Symbol>` directly,
       # not the AST `TypeParam` object (those live on the AST level).
+      #
+      # When `cache_store` is set, the loader fetches the entire
+      # type-parameter-name table once (per process) through
+      # {Cache::RbsClassTypeParamNames.fetch} and answers point
+      # lookups from it. Cold runs build the table once and persist
+      # it; warm runs (and a separate loader sharing the same Store)
+      # skip the env walk entirely.
       def class_type_param_names(class_name)
+        if cache_store
+          key = class_name.to_s.delete_prefix("::")
+          return type_param_names_table.fetch(key, []).dup
+        end
+
         definition = instance_definition(class_name)
         return [] unless definition
 
@@ -151,10 +251,25 @@ module Rigor
       #   should keep using {#constant_type} for point lookups.
       def constant_names
         env.constant_decls.keys.map(&:to_s)
-      rescue StandardError
+      rescue ::RBS::BaseError
         []
       end
 
+      # Yields `(name, entry)` for every RBS constant declaration
+      # currently loaded into the environment. The cache producer
+      # uses this to materialise the constant-type table without
+      # going back through {#constant_type} (which would recurse
+      # back into the cache when `cache_store` is set).
+      def each_constant_decl
+        return enum_for(:each_constant_decl) unless block_given?
+
+        env.constant_decls.each do |rbs_name, entry|
+          yield rbs_name.to_s, entry
+        end
+      rescue ::RBS::BaseError
+        # fail-soft: a broken RBS environment yields no entries.
+      end
+
       # Slice A constant-value lookup. Returns the translated
       # `Rigor::Type` for a non-class constant declaration
       # (`BUCKETS: Array[Symbol]`, `DEFAULT_PATH: String`, ...) or
@@ -164,23 +279,112 @@ module Rigor
       # nil; the loader does NOT consult the class declarations
       # here — class objects are still resolved through
       # {#class_known?} and `Environment#singleton_for_name`.
+      #
+      # When `cache_store` is set, the loader fetches the entire
+      # translated constant table once (per process) through
+      # {Cache::RbsConstantTable.fetch} and answers point lookups
+      # from it. Cold runs pay the translation cost up-front and
+      # write the result to disk; warm runs skip the translation
+      # entirely and pay only a `Marshal.load` of the table.
       def constant_type(name)
         rbs_name = parse_type_name(name)
         return nil unless rbs_name
 
+        if cache_store
+          constant_type_table[rbs_name.to_s]
+        else
+          translate_constant_decl(rbs_name)
+        end
+      rescue ::RBS::BaseError
+        nil
+      end
+
+      private
+
+      def constant_type_table
+        @constant_type_table ||= begin
+          require_relative "../cache/rbs_constant_table"
+          Cache::RbsConstantTable.fetch(loader: self, store: cache_store)
+        end
+      end
+
+      def known_class_names_set
+        @known_class_names_set ||= begin
+          require_relative "../cache/rbs_known_class_names"
+          Cache::RbsKnownClassNames.fetch(loader: self, store: cache_store)
+        end
+      end
+
+      def type_param_names_table
+        @type_param_names_table ||= begin
+          require_relative "../cache/rbs_class_type_param_names"
+          Cache::RbsClassTypeParamNames.fetch(loader: self, store: cache_store)
+        end
+      end
+
+      def cached_class_known(name)
+        rbs_name = parse_type_name(name)
+        return false unless rbs_name
+
+        known_class_names_set.include?(rbs_name.to_s)
+      rescue ::RBS::BaseError
+        false
+      end
+
+      def translate_constant_decl(rbs_name)
         entry = env.constant_decls[rbs_name]
         return nil unless entry
 
         translated = Inference::RbsTypeTranslator.translate(entry.decl.type)
         translated unless translated.is_a?(Type::Bot)
-      rescue StandardError
-        nil
       end
 
-      private
-
       def env
-        @state[:env] ||= build_env
+        @state[:env] ||= cache_store ? cached_env : build_env
+      end
+
+      def cached_env
+        require_relative "../cache/rbs_environment"
+        Cache::RbsEnvironment.fetch(loader: self, store: cache_store)
+      end
+
+      # Per-process Hash<String, RBS::Definition> for the instance
+      # side. Loaded once on first miss through the
+      # {Cache::RbsInstanceDefinitions} producer (single Marshal
+      # blob); subsequent calls are pure Hash lookups. Cold runs
+      # build every known class once and persist; warm runs (and
+      # other loaders sharing the same Store) skip the
+      # `RBS::DefinitionBuilder.build_instance` work entirely.
+      def cached_instance_definition(class_name)
+        instance_definitions_table[normalise_class_key(class_name)]
+      end
+
+      def instance_definitions_table
+        @state[:instance_definitions_table] ||= begin
+          require_relative "../cache/rbs_instance_definitions"
+          Cache::RbsInstanceDefinitions.fetch(loader: self, store: cache_store)
+        end
+      end
+
+      def cached_singleton_definition(class_name)
+        singleton_definitions_table[normalise_class_key(class_name)]
+      end
+
+      def singleton_definitions_table
+        @state[:singleton_definitions_table] ||= begin
+          require_relative "../cache/rbs_instance_definitions"
+          Cache::RbsSingletonDefinitions.fetch(loader: self, store: cache_store)
+        end
+      end
+
+      # The cache producers persist class names in
+      # `RBS::TypeName#to_s` form (top-level prefixed
+      # `"::Hash"`); plain-name lookups (`"Hash"`) normalise
+      # before the Hash query so callers stay agnostic to the
+      # prefix.
+      def normalise_class_key(class_name)
+        s = class_name.to_s
+        s.start_with?("::") ? s : "::#{s}"
       end
 
       def builder
@@ -188,23 +392,7 @@ module Rigor
       end
 
       def build_env
-        rbs_loader = RBS::EnvironmentLoader.new
-        @libraries.each do |library|
-          # Phase 2a deliberately fails-soft on unknown stdlib libraries
-          # so a stale `.rigor.yml` (or future config plumbing) does not
-          # take down the whole analyzer. Phase 2b will surface this
-          # through diagnostics once the configuration layer can name
-          # the offending source. The unknown-library check happens at
-          # `from_loader` time, not at `add` time, so we have to gate
-          # ahead of `add`.
-          next unless rbs_loader.has_library?(library: library, version: nil)
-
-          rbs_loader.add(library: library, version: nil)
-        end
-        @signature_paths.each do |path|
-          rbs_loader.add(path: path) if path.directory?
-        end
-        RBS::Environment.from_loader(rbs_loader).resolve_type_names
+        self.class.build_env_for(libraries: @libraries, signature_paths: @signature_paths)
       end
 
       def build_instance_definition(class_name)
@@ -213,7 +401,7 @@ module Rigor
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_instance(rbs_name)
-      rescue StandardError
+      rescue ::RBS::BaseError
         nil
       end
 
@@ -223,7 +411,7 @@ module Rigor
         return nil unless env.class_decls.key?(rbs_name)
 
         builder.build_singleton(rbs_name)
-      rescue StandardError
+      rescue ::RBS::BaseError
         nil
       end
 
@@ -233,7 +421,7 @@ module Rigor
 
         s = "::#{s}" unless s.start_with?("::")
         RBS::TypeName.parse(s)
-      rescue StandardError
+      rescue ::RBS::BaseError
         nil
       end
 
@@ -246,7 +434,7 @@ module Rigor
         # them under one map post-resolution. Aliases live in their
         # own table.
         env.class_decls.key?(rbs_name) || env.class_alias_decls.key?(rbs_name)
-      rescue StandardError
+      rescue ::RBS::BaseError
         false
       end
     end

data/lib/rigor/environment.rb

@@ -76,11 +76,20 @@ module Rigor
       #   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 {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]
-      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil)
+      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil)
         resolved_paths = signature_paths || default_signature_paths(root)
         merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s)).uniq
-        loader = RbsLoader.new(libraries: merged_libraries, signature_paths: resolved_paths)
+        loader = RbsLoader.new(
+          libraries: merged_libraries,
+          signature_paths: resolved_paths,
+          cache_store: cache_store
+        )
         new(rbs_loader: loader)
       end
 

data/lib/rigor/flow_contribution/conflict.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Records a contradiction between two or more flow contributions
+    # detected during {Merger.merge}. Carried on {MergeResult#conflicts}
+    # so the analyzer / formatter can surface a `:contribution_merge`
+    # diagnostic per ADR-2 § "Plugin Contribution Merging".
+    #
+    # ADR-2 § "Plugin Contribution Merging" rules out first-wins /
+    # last-wins behaviour: when contributions conflict, both sources
+    # are reported and the merger falls back to the nearest non-
+    # conflicting higher-tier (or default) value for the affected
+    # `(target, edge, kind)` slot. The conflict object is the
+    # carrier of that report.
+    #
+    # Slice-3 conflict reasons:
+    #
+    # - `:return_type_collapse` — two return-type contributions
+    #   intersect to `bot`.
+    # - `:exceptional_disagreement` — two contributions assert
+    #   incompatible non-`nil` exceptional effects.
+    # - `:lower_tier_contradiction` — a lower-tier contribution
+    #   would weaken or contradict a higher-tier proof.
+    CONFLICT_VALID_REASONS = %i[
+      return_type_collapse
+      exceptional_disagreement
+      lower_tier_contradiction
+    ].freeze
+
+    Conflict = Data.define(:target, :edge, :kind, :reason, :provenances, :message) do
+      def initialize(target:, edge:, kind:, reason:, provenances:, message:) # rubocop:disable Metrics/ParameterLists
+        unless CONFLICT_VALID_REASONS.include?(reason)
+          raise ArgumentError,
+                "FlowContribution::Conflict reason must be one of " \
+                "#{CONFLICT_VALID_REASONS.inspect}, got #{reason.inspect}"
+        end
+
+        super(target: target, edge: edge, kind: kind, reason: reason,
+              provenances: provenances.dup.freeze, message: message.to_s.dup.freeze)
+      end
+
+      def to_h
+        {
+          "target" => target.to_s,
+          "edge" => edge.to_s,
+          "kind" => kind.to_s,
+          "reason" => reason.to_s,
+          "sources" => provenances.map { |p| p.respond_to?(:to_h) ? p.to_h : p.to_s },
+          "message" => message
+        }
+      end
+
+      # ADR-7 § "Slice 5-C" — converts the conflict into a
+      # `Rigor::Analysis::Diagnostic` for the run result.
+      # Carries `source_family: :contribution_merge` so the
+      # qualified-rule formatter (slice 5 formatter half,
+      # `ef730b2`) prefixes the rule id with
+      # `contribution_merge.` and the JSON output side-bands
+      # `source_family` + `rule` for plugin attribution.
+      #
+      # The `rule` identifier is the kebab-case form of the
+      # conflict reason (`return_type_collapse` →
+      # `return-type-collapse`, etc.) so the qualified rule
+      # reads `[contribution_merge.return-type-collapse]` in
+      # the standard text stream.
+      def to_diagnostic(path:, line:, column:, severity: :error)
+        require_relative "../analysis/diagnostic" unless defined?(Rigor::Analysis::Diagnostic)
+        Rigor::Analysis::Diagnostic.new(
+          path: path,
+          line: line,
+          column: column,
+          message: message,
+          severity: severity,
+          rule: reason.to_s.tr("_", "-"),
+          source_family: :contribution_merge
+        )
+      end
+    end
+  end
+end

data/lib/rigor/flow_contribution/element.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Tagged element flattening of a {FlowContribution} bundle —
+    # the analyzer-internal representation [ADR-2 § "Flow
+    # Contribution Bundle"](../../../docs/adr/2-extension-api.md)
+    # routes through the {Merger}.
+    #
+    # The flattening is **mechanical, deterministic, and round-
+    # trippable** with the bundle: every non-empty slot expands
+    # into one or more elements keyed by `(target, edge, kind)`,
+    # and an array of elements rebuilds an equivalent bundle when
+    # routed through `Merger.merge`.
+    #
+    # Plugin authors should not depend on the element shape — the
+    # bundle is the public contract; the element list is the
+    # implementation surface the merge policy operates over.
+    ELEMENT_VALID_EDGES = %i[normal truthy falsey post_return exceptional].freeze
+    ELEMENT_VALID_KINDS = %i[
+      return_type
+      truthy_fact
+      falsey_fact
+      post_return_fact
+      mutation
+      invalidation
+      exception
+      role
+    ].freeze
+
+    Element = Data.define(:target, :edge, :kind, :payload, :provenance) do
+      def initialize(target:, edge:, kind:, payload:, provenance:)
+        unless ELEMENT_VALID_EDGES.include?(edge)
+          raise ArgumentError,
+                "FlowContribution::Element edge must be one of " \
+                "#{ELEMENT_VALID_EDGES.inspect}, got #{edge.inspect}"
+        end
+
+        unless ELEMENT_VALID_KINDS.include?(kind)
+          raise ArgumentError,
+                "FlowContribution::Element kind must be one of " \
+                "#{ELEMENT_VALID_KINDS.inspect}, got #{kind.inspect}"
+        end
+
+        super
+      end
+
+      def merge_key
+        [target, edge, kind]
+      end
+    end
+  end
+end

data/lib/rigor/flow_contribution/fact.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Canonical slot payload for the four edge-aware fact slots
+    # (`truthy_facts`, `falsey_facts`, `post_return_facts`, plus
+    # the equivalent under `mutations` / `invalidations` /
+    # `role_conformance` once those carriers grow Fact-shaped
+    # variants).
+    #
+    # ADR-7 § "Slice 4-A" pins this object as the **single
+    # canonical translation target** for the four parallel
+    # contribution carriers the engine has carried so far:
+    #
+    # 1. Built-in narrowing rules' direct fact emission
+    #    (Inference::Narrowing#predicate_scopes).
+    # 2. RBS::Extended `predicate-if-*` directives
+    #    (`Rigor::RbsExtended::PredicateEffect`).
+    # 3. RBS::Extended `assert*` directives
+    #    (`Rigor::RbsExtended::AssertEffect`).
+    # 4. Future plugin contributions (slice 5 emission protocol).
+    #
+    # Each of those four carriers translates to / from Fact at
+    # its boundary; downstream of {Rigor::FlowContribution#to_element_list}
+    # and {Rigor::FlowContribution::Merger.merge}, every slot
+    # payload is a Fact (or a value that the merger compares by
+    # equality and never inspects). The typed `RbsExtended::*Effect`
+    # carriers stay internal to the parser side — they hold the
+    # source-text shape, but lose their identity at the
+    # `read_flow_contribution` boundary.
+    #
+    # ## 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_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.
+    # - `type`: a `Rigor::Type::*` (Nominal, Refined,
+    #   IntegerRange, Difference, …) the fact narrows the
+    #   target toward (when `negative` is false) or away from
+    #   (when `negative` is true).
+    # - `negative`: `true` for the `~T` negation form
+    #   (`predicate-if-true x is ~Integer`), `false` for the
+    #   plain positive form. Mirrors the `negative` field on
+    #   `PredicateEffect` / `AssertEffect`.
+    #
+    # The `target` accessor returns `:self` for self-targeted
+    # facts and `[:parameter, name]` otherwise — that's the
+    # 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 = Data.define(:target_kind, :target_name, :type, :negative) do
+      def initialize(target_kind:, target_name:, type:, negative: false)
+        unless FACT_VALID_TARGET_KINDS.include?(target_kind)
+          raise ArgumentError,
+                "FlowContribution::Fact target_kind must be one of " \
+                "#{FACT_VALID_TARGET_KINDS.inspect}, got #{target_kind.inspect}"
+        end
+
+        unless target_name.is_a?(Symbol)
+          raise ArgumentError,
+                "FlowContribution::Fact target_name must be a Symbol, got #{target_name.inspect}"
+        end
+
+        super
+      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.
+      def target
+        target_kind == :self ? :self : [target_kind, target_name]
+      end
+
+      def negative?
+        negative == true
+      end
+    end
+  end
+end

data/lib/rigor/flow_contribution/merge_result.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Rigor
+  class FlowContribution
+    # Result of folding any number of {FlowContribution} bundles
+    # through {Merger.merge}. Surfaces the merged content slot-by-
+    # slot, the ordered list of contributing provenances, and the
+    # {Conflict} list collected along the way.
+    #
+    # The merge result is a sibling shape of {FlowContribution} —
+    # the analyzer reads from it to drive narrowing / dispatch /
+    # diagnostics, and the formatter reads from it to surface
+    # plugin / RBS::Extended provenance. The shape is derived per
+    # ADR-2 § "Plugin Contribution Merging"; see
+    # [`docs/internal-spec/flow-contribution-merger.md`](../../../docs/internal-spec/flow-contribution-merger.md)
+    # for the slice-3 normative description.
+    class MergeResult
+      attr_reader :return_type, :truthy_facts, :falsey_facts, :post_return_facts,
+                  :mutations, :invalidations, :exceptional, :role_conformance,
+                  :provenances, :conflicts
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(return_type: nil, truthy_facts: [], falsey_facts: [],
+                     post_return_facts: [], mutations: [], invalidations: [],
+                     exceptional: nil, role_conformance: [],
+                     provenances: [], conflicts: [])
+        # rubocop:enable Metrics/ParameterLists
+        @return_type = return_type
+        @truthy_facts = truthy_facts.dup.freeze
+        @falsey_facts = falsey_facts.dup.freeze
+        @post_return_facts = post_return_facts.dup.freeze
+        @mutations = mutations.dup.freeze
+        @invalidations = invalidations.dup.freeze
+        @exceptional = exceptional
+        @role_conformance = role_conformance.dup.freeze
+        @provenances = provenances.dup.freeze
+        @conflicts = conflicts.dup.freeze
+        freeze
+      end
+
+      def conflict?
+        !@conflicts.empty?
+      end
+
+      def empty? # rubocop:disable Metrics/CyclomaticComplexity
+        @return_type.nil? && @truthy_facts.empty? && @falsey_facts.empty? &&
+          @post_return_facts.empty? && @mutations.empty? && @invalidations.empty? &&
+          @exceptional.nil? && @role_conformance.empty?
+      end
+
+      def to_h
+        {
+          "return_type" => return_type,
+          "truthy_facts" => truthy_facts,
+          "falsey_facts" => falsey_facts,
+          "post_return_facts" => post_return_facts,
+          "mutations" => mutations,
+          "invalidations" => invalidations,
+          "exceptional" => exceptional,
+          "role_conformance" => role_conformance,
+          "provenances" => provenances.map { |p| p.respond_to?(:to_h) ? p.to_h : p },
+          "conflicts" => conflicts.map(&:to_h)
+        }
+      end
+    end
+  end
+end