rigortype 0.4.7 → 0.4.8

data/lib/rigor/sig_gen/skip_reason_catalog.rb

@@ -149,6 +149,38 @@ module Rigor
           next_step: "Generate signatures for the overriding subclass too — widen the `sig-gen` path set to " \
                      "cover it — and the parent's declaration becomes safe to emit."
         ),
+        "sig.skipped.overridden-bot" => Entry.new(
+          id: "sig.skipped.overridden-bot",
+          summary: "The method's body never returns, and the analysed code overrides the method.",
+          explanation: "The inferred return is `bot`, but the analysed code defines the method again, with `def` " \
+                       "or `define_method`: a subclass (signed or not), a class that includes the method's module, " \
+                       "a module included later or prepended, or an extending class's own singleton method. " \
+                       "`bot` describes only the base body the overrides replace, and every override returns a " \
+                       "value, so the declaration would contradict each of them (#3029).",
+          next_step: "Declare the return every implementation shares (often `untyped` or the overrides' common " \
+                     "type) by hand in `sig/`."
+        ),
+        "sig.skipped.abstract-method" => Entry.new(
+          id: "sig.skipped.abstract-method",
+          summary: "The method is abstract: its body only raises an error asking for an implementation.",
+          explanation: "The body ends in `raise NotImplementedError`, in an error class named `Abstract...` or " \
+                       "`NotImplemented...`, or in a raise whose message asks for the method to be implemented, " \
+                       "defined or overridden. Its inferred return is `bot`, but the method is meant to be " \
+                       "replaced, and the replacements may live outside the analysed code, as in a plugin gem " \
+                       "(#3029).",
+          next_step: "Declare the return the implementations must provide by hand in `sig/`."
+        ),
+        "sig.skipped.template-method" => Entry.new(
+          id: "sig.skipped.template-method",
+          summary: "The method's `bot` return may come only from calling an overridden or abstract method.",
+          explanation: "The inferred return is `bot`, and the body does not end in a direct `raise`, `fail`, " \
+                       "`throw`, `exit` or `abort`. It calls a method the analysed code overrides or declares " \
+                       "abstract, directly or through a chain of self-dispatched calls, so the `bot` may be only " \
+                       "the base body of that call, which an override replaces at run time. The call is matched " \
+                       "by name, whatever its receiver (#3029).",
+          next_step: "Declare the return by hand in `sig/`, usually the return the overridden hook's " \
+                     "implementations share."
+        ),
         "sig.skipped.top-level-def" => Entry.new(
           id: "sig.skipped.top-level-def",
           summary: "A top-level `def` defines a private `Object` method, and sig-gen writes no signature for it.",
@@ -171,6 +203,21 @@ module Rigor
                        "writes neither rather than guess (#1968).",
           next_step: "Move the visibility call to the module body's own statements, or name the methods it " \
                      "should cover (`public :name`, `module_function :name`), so the reading is certain."
+        ),
+        "sig.skipped.platform-guarded" => Entry.new(
+          id: "sig.skipped.platform-guarded",
+          summary: "The method is defined in a file loaded only under a platform guard, so its proposal was withheld.",
+          explanation: "The file is `require`d / `require_relative`d only inside a conditional on " \
+                       "`RUBY_ENGINE`, `RUBY_PLATFORM` or `defined?(…)`, so it is not an ordinary definition " \
+                       "for every platform — the shape is `if RUBY_ENGINE == 'truffleruby'` guarding a " \
+                       "pure-Ruby fallback whose real methods a C extension provides elsewhere. sig-gen " \
+                       "withholds the proposal when another scanned file also defines the method (the " \
+                       "guarded copy would compete with or duplicate the definition this platform loads), " \
+                       "or when the inferred return is `bot` — the shape a raising stub takes, and never a " \
+                       "contract worth writing from a file the current engine may never read (#3035).",
+          next_step: "Declare the method for the platform the project targets — hand-write the `sig/` " \
+                     "entry, or cover the file that defines it on this platform in the `sig-gen` paths — " \
+                     "rather than taking the guarded file's stub as the contract."
         )
       }.freeze
 

data/lib/rigor/sig_gen/writer.rb

@@ -38,6 +38,21 @@ module Rigor
                               :target, keyword_init: true)
       private_constant :MergeState
 
+      # #2576 — a target the writer cannot write (a permission denial, a directory sitting where the
+      # `.rbs` belongs, a parent path that is a regular file) is a bad `--write` invocation, not a
+      # crash: the command
+      # reports it as the same usage error `rigor init --path` gives and exits 64. Carries the target
+      # and the stripped Errno reason so the CLI prints `cannot write PATH: REASON` without
+      # re-parsing the message.
+      class WriteError < StandardError
+        attr_reader :target_path
+
+        def initialize(target_path, error)
+          @target_path = target_path.to_s
+          super("cannot write #{@target_path}: #{error.message.sub(/ @ .*\z/m, '')}")
+        end
+      end
+
       # The target routing this writer applies; the generator maps candidates through it to ask {#accepts_target?}.
       attr_reader :path_mapper
 
@@ -186,6 +201,8 @@ module Rigor
         end
 
         target.exist? ? update_existing(source_path, target, candidates) : create_new(source_path, target, candidates)
+      rescue SystemCallError => e
+        raise WriteError.new(target, e)
       end
 
       # Deliberately NARROWER than {Classification::EMITTABLE}: the write path has never produced a
@@ -222,6 +239,8 @@ module Rigor
         end
         WriteResult.new(source_path: source_path, target_path: target,
                         action: :created, applied: candidates)
+      rescue SystemCallError => e
+        raise WriteError.new(target, e)
       end
 
       # ADR-14 gap-#3 follow-up (c): when one candidate's `class_name` is a strict prefix of another's, emit a
@@ -429,6 +448,8 @@ module Rigor
                         action: :updated, applied: state.applied, skipped: state.skipped,
                         left_unreadable: state.left_unreadable, replaced: state.replaced,
                         repaired_headers: state.repaired_headers)
+      rescue SystemCallError => e
+        raise WriteError.new(target, e)
       end
 
       # Applies every class group, then every requested shell, then normalises the layout the three steps

data/lib/rigor/sig_gen.rb

@@ -5,6 +5,7 @@ require_relative "sig_gen/classification"
 require_relative "sig_gen/effect_annotation"
 require_relative "sig_gen/inline_declarations"
 require_relative "sig_gen/method_candidate"
+require_relative "sig_gen/platform_guarded_files"
 require_relative "sig_gen/observed_call"
 require_relative "sig_gen/meta_class_shape"
 require_relative "sig_gen/type_elaborator"

data/lib/rigor/source/forwardable_delegators.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "literals"
+
+module Rigor
+  module Source
+    # Issue #2793 — the methods a `Forwardable` / `SingleForwardable` delegator macro defines, read off its syntax
+    # alone. Ruby 4.0's `forwardable.rb` is the oracle for each row:
+    #
+    # - `def_instance_delegator(acc, m, ali = m)` defines `ali` on the instance side;
+    # - `def_instance_delegators(acc, *ms)` defines each `m` but `__send__` and `__id__`, instance side (the two are
+    #   recorded anyway: `BasicObject` declares both, so a recorded entry changes no answer);
+    # - `instance_delegate(ms => acc)` defines each key name (a name or an array of them), instance side;
+    # - `def_single_delegator(s)` and `single_delegate` are the same on the singleton side;
+    # - `def_delegator(s)` and `delegate` are the same on the side the `extend` decides.
+    #
+    # `def_delegator(s)` and `delegate` are `Forwardable`'s instance aliases and `SingleForwardable`'s singleton
+    # ones, so their side is {AMBIGUOUS} and the caller settles it from the `extend` it has seen. `def_delegator :@x,
+    # :last, :final` defines `final` and never `last`.
+    #
+    # A name the syntax does not spell (`def_delegators :@x, *NAMES`, `delegate names => :@x`) makes the delegation
+    # {Delegation#open?}: the macro defines methods no reader can enumerate. `delegate` takes Forwardable's
+    # single-hash form only, so ActiveSupport's `delegate :a, to: :b` (positional names before a `to:` key) is
+    # not read here.
+    module ForwardableDelegators
+      AMBIGUOUS = :ambiguous
+
+      # The names a delegator macro defines, on which side, and whether it also defines names its syntax hides.
+      Delegation = Data.define(:side, :names, :open) do
+        def open? = open
+      end
+
+      # `[side, shape]` per macro: `:alias` takes `(accessor, method, alias = method)`, `:list` takes `(accessor,
+      # *methods)`, `:hash` takes `(methods => accessor, …)`.
+      MACROS = Ractor.make_shareable(
+        {
+          def_instance_delegator: %i[instance alias], def_instance_delegators: %i[instance list],
+          instance_delegate: %i[instance hash],
+          def_single_delegator: %i[singleton alias], def_single_delegators: %i[singleton list],
+          single_delegate: %i[singleton hash],
+          def_delegator: [AMBIGUOUS, :alias], def_delegators: [AMBIGUOUS, :list], delegate: [AMBIGUOUS, :hash]
+        }
+      )
+
+      private_constant :MACROS
+
+      module_function
+
+      # The {Delegation} of an implicit-self (or `self.`) delegator macro call, or nil for any other call, and for
+      # one whose arguments are not a shape the macro accepts.
+      def of(call_node)
+        return nil unless call_node.is_a?(Prism::CallNode)
+        return nil unless call_node.receiver.nil? || call_node.receiver.is_a?(Prism::SelfNode)
+
+        side, shape = MACROS[call_node.name]
+        return nil if side.nil?
+
+        arguments = call_node.arguments&.arguments || []
+        return Delegation.new(side: side, names: [].freeze, open: true) if unplaceable_splat?(shape, arguments)
+
+        names, open = case shape
+                      when :alias then alias_names(arguments)
+                      when :list then list_names(arguments)
+                      else hash_names(arguments)
+                      end
+        return nil if names.nil?
+
+        Delegation.new(side: side, names: names.freeze, open: open)
+      end
+
+      # A splat (`def_delegator(*ARGS)`, `def_delegators(*ARGS)`, `delegate(*pairs)`) hides which argument is the
+      # accessor and which a name, so the macro may define any name. A splat after the accessor of the list form is
+      # only a hidden name, and {#list_names} reads the literal names beside it.
+      def unplaceable_splat?(shape, arguments)
+        splats = arguments.each_index.select { |index| arguments[index].is_a?(Prism::SplatNode) }
+        return false if splats.empty?
+
+        shape != :list || splats.include?(0)
+      end
+
+      def alias_names(arguments)
+        return nil unless (2..3).cover?(arguments.size)
+
+        name = Literals.symbol_or_string(arguments.last)
+        name.nil? ? [[], true] : [[name], false]
+      end
+
+      def list_names(arguments)
+        return nil if arguments.empty?
+
+        rest = arguments.drop(1)
+        names = rest.filter_map { |argument| Literals.symbol_or_string(argument) }
+        [names, names.size != rest.size]
+      end
+
+      def hash_names(arguments)
+        return nil unless arguments.size == 1
+
+        hash = arguments.first
+        return nil unless hash.is_a?(Prism::KeywordHashNode) || hash.is_a?(Prism::HashNode)
+
+        names = []
+        open = false
+        hash.elements.each do |element|
+          return [[], true] unless element.is_a?(Prism::AssocNode)
+
+          keys = key_names(element.key)
+          keys.nil? ? (open = true) : names.concat(keys)
+        end
+        [names, open]
+      end
+
+      # The names a hash key spells — a literal name, or an array of them — or nil when any is computed.
+      def key_names(key)
+        elements = key.is_a?(Prism::ArrayNode) ? key.elements : [key]
+        names = elements.map { |element| Literals.symbol_or_string(element) }
+        names.include?(nil) ? nil : names
+      end
+    end
+  end
+end

data/lib/rigor/source/node_children.rb

@@ -109,6 +109,19 @@ module Rigor
       def each_child(node, &)
         node.rigor_each_child(&) if node.is_a?(Prism::Node)
       end
+
+      # #2455 — whether `root` nests deeper than `bound` levels, measured without recursion (the question is asked after
+      # the recursive walkers ran out of stack). Stops as soon as one path passes the bound.
+      def self.nested_deeper_than?(root, bound)
+        stack = [[root, 1]]
+        until stack.empty?
+          node, depth = stack.pop
+          return true if depth > bound
+
+          node.rigor_each_child { |child| stack << [child, depth + 1] }
+        end
+        false
+      end
     end
   end
 end

data/lib/rigor/type/combinator.rb

@@ -46,6 +46,27 @@ module Rigor
         @untyped
       end
 
+      # ADR-130 WD2 — the parity predicate. Every site that keys a leniency on `untyped` asks this instead of testing
+      # a `Dynamic`'s facet for `Top` or comparing with {untyped}, so a value whose facet parity erases
+      # ({erased_facet?}) reads as `untyped` everywhere but member dispatch. `spec/rigor/type/untyped_parity_spec.rb`
+      # flags the raw spellings it knows outside this module. True for `Dynamic[top]` and for a plugin-interface
+      # value, `Dynamic[Rigor::Plugin::_Scope]`.
+      def untyped?(type)
+        return false unless type.is_a?(Dynamic)
+
+        facet = type.static_facet
+        facet.is_a?(Top) || erased_facet?(facet)
+      end
+
+      # ADR-130 WD1 — true for a `Dynamic` facet that parity reads as `top`: the `Rigor::Plugin` interface carrier
+      # ({Interface}). {untyped?} answers true for it, and {merge_erased_members} merges it with `Dynamic[top]`.
+      # `spec/rigor/type/combinator_facet_erasure_spec.rb` also drives the merge through a stub facet. An engine
+      # hook, not public API.
+      def erased_facet?(facet)
+        facet.is_a?(Interface)
+      end
+      private_class_method :erased_facet?
+
       # Wraps the static facet in a Dynamic[T] carrier. Idempotent on the static facet so
       # Dynamic[Dynamic[T]] collapses to Dynamic[T] per the value-lattice algebra.
       def dynamic(static_facet)
@@ -821,7 +842,104 @@ module Rigor
 
           return [top] if flattened.any?(Top)
 
-          absorb_contained_members(unique_members(flattened))
+          absorb_contained_members(merge_erased_members(unique_members(flattened)))
+        end
+
+        # ADR-130 WD1 — a facet parity erases ({erased_facet?}) must not give a join a shape master's dedup would
+        # not: `Dynamic[_A] | Dynamic[top]` is `Dynamic[top]`, and so are the same members anywhere inside a carrier
+        # that holds a type ({TYPE_CHILDREN}). Members equal after {erase_facets} merge into the erased form, at the
+        # first one's position; a member no other matches keeps its facet, and {absorb_contained_members} compares
+        # the erased forms too. The facet scan runs on every join and allocates nothing (no enumerator, no array),
+        # so the merge costs only where a facet is present, which is nowhere until ADR-130 slice 1b.
+        def merge_erased_members(members)
+          return members if members.size < 2
+          return members unless members.any? { |member| facet_bearing?(member) }
+
+          erased = members.map { |member| erase_facets(member) }
+          counts = Hash.new(0)
+          erased.each { |type| counts[type] += 1 }
+          merged = {}
+          result = []
+          members.each_with_index do |member, index|
+            type = erased[index]
+            if counts[type] == 1
+              result << member
+            elsif !merged.key?(type)
+              merged[type] = true
+              result << type
+            end
+          end
+          result
+        end
+
+        def facet_bearing?(type)
+          return erased_facet?(type.static_facet) || facet_bearing?(type.static_facet) if type.is_a?(Dynamic)
+
+          readers = TYPE_CHILDREN[type.class]
+          return false if readers.nil?
+
+          readers.each { |reader| return true if child_facet_bearing?(type.public_send(reader)) }
+          false
+        end
+
+        def child_facet_bearing?(child)
+          case child
+          when Array then child.any? { |type| facet_bearing?(type) }
+          when Hash
+            child.each_value { |type| return true if facet_bearing?(type) }
+            false
+          else facet_bearing?(child)
+          end
+        end
+
+        # `type` with every facet {erased_facet?} accepts rewritten to `top`, through every carrier
+        # {TYPE_CHILDREN} lists. The identity, by reference, on a type that bears none. A facet-bearing `Dynamic`
+        # is never `Dynamic[top]`, so {untyped?} answers the hook for it here.
+        def erase_facets(type)
+          return type unless facet_bearing?(type)
+
+          case type
+          when Dynamic then untyped?(type) ? untyped : dynamic(erase_facets(type.static_facet))
+          when Union then union(*erase_each(type.members))
+          when Intersection then intersection(*erase_each(type.members))
+          when Tuple then tuple_of(*erase_each(type.elements))
+          when Nominal then nominal_of(type.class_name, type_args: erase_each(type.type_args))
+          when HashShape then erase_shape_facets(type)
+          else erase_wrapper_facets(type)
+          end
+        end
+
+        def erase_wrapper_facets(type)
+          case type
+          when Difference then Difference.new(erase_facets(type.base), erase_facets(type.removed))
+          when Refined then Refined.new(erase_facets(type.base), type.predicate_id)
+          when Maybe then Maybe.new(erase_facets(type.value_type))
+          when Result then Result.new(erase_facets(type.ok_type), erase_facets(type.err_type))
+          else erase_bearer_facets(type)
+          end
+        end
+
+        def erase_bearer_facets(type)
+          case type
+          when App then App.new(type.uri, erase_each(type.args), bound: erase_facets(type.bound))
+          when BoundMethod
+            BoundMethod.new(receiver_type: erase_facets(type.receiver_type), method_name: type.method_name)
+          when DataInstance then DataInstance.new(erase_values(type.members), type.class_name)
+          when StructInstance then StructInstance.new(erase_values(type.members), type.class_name)
+          # The facet itself, erased apart from its `Dynamic` (which erases whole, to `untyped`).
+          when Interface then Interface.new(type.name, erase_each(type.type_args))
+          else type
+          end
+        end
+
+        def erase_each(types) = types.map { |type| erase_facets(type) }
+
+        def erase_values(pairs) = pairs.transform_values { |type| erase_facets(type) }
+
+        def erase_shape_facets(shape)
+          HashShape.new(erase_values(shape.pairs),
+                        required_keys: shape.required_keys, optional_keys: shape.optional_keys,
+                        read_only_keys: shape.read_only_keys, extra_keys: shape.extra_keys)
         end
 
         # Drops every member another member already contains, so the join after a guard names one set
@@ -835,15 +953,30 @@ module Rigor
         # The `!absorbed_by?(other, member)` re-check costs one predicate call per pair that absorbed
         # at all, and it is what makes "both arms dropped" unrepresentable should a future clause make
         # the relation symmetric on a pair of distinct members.
+        #
+        # ADR-130 WD1 — the relation reads each member's erased form ({erase_facets}), so a facet does not keep an
+        # arm master absorbs: `[Dynamic[_A]] | [Dynamic[top] | Integer]` drops the first arm as master's
+        # `[Dynamic[top]] | [Dynamic[top] | Integer]` does. Without a facet the readings are the members themselves.
         def absorb_contained_members(members)
           return members unless members.any? { |m| absorbable_member?(m) }
 
           members = join_sequence_elements(members)
-          members.reject do |member|
-            absorbable_member?(member) &&
-              members.any? do |other|
-                !other.equal?(member) && absorbed_by?(member, other) && !absorbed_by?(other, member)
-              end
+          readings = members.any? { |member| facet_bearing?(member) } ? members.map { |m| erase_facets(m) } : members
+          # `each_index`, not `each_with_index`: the Enumerable form allocates an iterator object on every join.
+          kept = []
+          members.each_index do |index|
+            member = members[index]
+            kept << member unless absorbable_member?(member) && absorbed_reading?(readings, index)
+          end
+          kept
+        end
+
+        # `any?` rather than an early `return` from an `each` block: a non-local return allocates on every absorbed
+        # member. Readings are distinct objects (the members were made unique, and an erased form is a new object).
+        def absorbed_reading?(readings, index)
+          reading = readings[index]
+          readings.any? do |wider|
+            !wider.equal?(reading) && absorbed_by?(reading, wider) && !absorbed_by?(wider, reading)
           end
         end
 
@@ -1040,10 +1173,18 @@ module Rigor
         # need not render alike (`Constant[1..2]` and `Constant[1..2.0]`), so equality is not a safe key. A
         # non-main Ractor may not read the module's ivar, so a pool worker renders the key every time, as every
         # run did before.
+        #
+        # ADR-130 WD1 — a member bearing a facet sorts by its erased form's rendering, so a facet does not move it:
+        # `Dynamic[_A] | Dynamic[String]` keeps master's `Dynamic[String] | Dynamic[top]` order. The facet scan runs
+        # only when a key is rendered, and a member without a facet renders as it always did.
         def sort_key(member)
-          return member.describe(:short) unless Ractor.main?
+          return render_sort_key(member) unless Ractor.main?
 
-          @sort_keys[member] ||= member.describe(:short)
+          @sort_keys[member] ||= render_sort_key(member)
+        end
+
+        def render_sort_key(member)
+          (facet_bearing?(member) ? erase_facets(member) : member).describe(:short)
         end
       end
 
@@ -1052,6 +1193,21 @@ module Rigor
       # The main Ractor's {sort_key} memo, allocated here for the same reason.
       @sort_keys = ObjectSpace::WeakMap.new
 
+      # ADR-130 WD1 — the readers of every type a carrier holds, which facet erasure walks. A leaf lists none.
+      # `spec/rigor/type/combinator_facet_erasure_spec.rb` fails on a `Rigor::Type` carrier missing here, and on a
+      # listed carrier whose erasure leaves a facet in any of its type slots.
+      TYPE_CHILDREN = Ractor.make_shareable(
+        {
+          Top => [], Bot => [], Constant => [], IntegerRange => [], FloatRange => [], Singleton => [],
+          DataClass => [], StructClass => [],
+          Dynamic => %i[static_facet], Nominal => %i[type_args], Tuple => %i[elements], HashShape => %i[pairs],
+          Union => %i[members], Intersection => %i[members], Difference => %i[base removed], Refined => %i[base],
+          Maybe => %i[value_type], Result => %i[ok_type err_type], App => %i[args bound],
+          BoundMethod => %i[receiver_type], DataInstance => %i[members], StructInstance => %i[members],
+          Interface => %i[type_args]
+        }
+      )
+
       NIL_CONSTANT = Constant.new(nil)
       TRUE_CONSTANT = Constant.new(true)
       FALSE_CONSTANT = Constant.new(false)

data/lib/rigor/type/interface.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+require_relative "../value_semantics"
+require_relative "acceptance_router"
+require_relative "plain_lattice"
+
+module Rigor
+  module Type
+    # ADR-130 WD1 — an RBS interface under `Rigor::Plugin` (`_Scope`, `_Environment`, ...), as the facet of the
+    # `Dynamic` that carries a plugin-interface value: `Dynamic[Rigor::Plugin::_Scope]`. It appears only there.
+    # `Combinator.untyped?` reads such a `Dynamic` as `untyped`, and union normalisation erases it to `Dynamic[top]`
+    # wherever a join would otherwise keep an arm master does not, so the facet changes one behaviour: a call of a
+    # member the interface declares resolves through that member's RBS (`RbsDispatch`, ADR-130 WD3).
+    #
+    # `name` is spelled as `Nominal#class_name` is (`Rigor::Plugin::_Scope`), and `type_args` are the interface's
+    # type arguments, translated in the caller's context. Every other RBS interface still translates to
+    # `Dynamic[top]` (`RbsTypeTranslator`, ADR-130 WD4).
+    class Interface
+      attr_reader :name, :type_args
+
+      EMPTY_TYPE_ARGS = [].freeze
+      private_constant :EMPTY_TYPE_ARGS
+
+      def initialize(name, type_args = EMPTY_TYPE_ARGS)
+        raise ArgumentError, "name must be a String, got #{name.class}" unless name.is_a?(String)
+
+        @name = name.frozen? ? name : name.dup.freeze
+        @type_args = type_args.frozen? ? type_args : type_args.dup.freeze
+        freeze
+      end
+
+      def describe(verbosity = :short)
+        return name if type_args.empty?
+
+        "#{name}[#{type_args.map { |arg| arg.describe(verbosity) }.join(', ')}]"
+      end
+
+      # A facet never reaches erasure on its own (`Dynamic#erase_to_rbs` is `untyped`); spelled as RBS for a
+      # caller that erases the carrier directly.
+      def erase_to_rbs
+        return name if type_args.empty?
+
+        "#{name}[#{type_args.map(&:erase_to_rbs).join(', ')}]"
+      end
+
+      include Rigor::Type::PlainLattice
+
+      include Rigor::Type::AcceptanceRouter
+
+      include Rigor::ValueSemantics
+
+      value_fields :name, :type_args
+
+      def inspect
+        "#<Rigor::Type::Interface #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type.rb

@@ -28,6 +28,7 @@ require_relative "type/union"
 require_relative "type/difference"
 require_relative "type/refined"
 require_relative "type/intersection"
+require_relative "type/interface"
 require_relative "type/app"
 require_relative "type/result"
 require_relative "type/maybe"

data/lib/rigor/type_of_memo/serving.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Rigor
+  module TypeOfMemo
+    # G1's stage-4 form (ADR-129 WD5), mixed into {TypeOfMemo}'s singleton: on a would-be hit with
+    # `TypeOfMemo.enable!(serve: true)`, the memo serves the entry and checks it against a recomputation. For specs
+    # and audit tools; the CLI's `RIGOR_TYPE_OF_SHADOW=1` never serves.
+    module Serving
+      EMPTY = [].freeze
+      private_constant :EMPTY
+
+      private
+
+      # G1's stage-4 form (ADR-129 WD5) on one would-be hit:
+      # 1. recompute on the same scope objects with the memo suspended, in a capture and a priors window, and record
+      #    the final state of every entry either side touches; a recomputation that touched a Resource is a mismatch
+      #    and its answer stands;
+      # 2. undo the recomputation's Table writes and drop its journal records, which the served entry replaces;
+      # 3. serve the entry: validate its reads, merge them into the enclosing captures, replay its writes, and compare
+      #    the touched entries and the type with the recorded ones. A recomputation that raises where an entry exists
+      #    is a mismatch too.
+      def serve_hit(state, table, phase, scope, node, entry, &)
+        stored, reads, writes = entry.is_a?(Array) ? entry : [entry, EMPTY, EMPTY]
+        count(phase, :checked)
+        mark = state.journal_size
+        fresh, priors, refused = recompute(state, table, phase, scope, node, stored, &)
+        if refused
+          judge(state, phase, scope, node, stored, fresh, writes, priors, refused)
+          return fresh
+        end
+
+        serve(state, phase, scope, node, stored, fresh, [reads, writes, priors, mark])
+      end
+
+      # Steps 2 and 3 of {#serve_hit}. An error in them (a replay into a store the entry outlived) is a mismatch,
+      # counted rather than raised into the typing path's rescues. The recomputation's type is answered; the tables may
+      # hold a partial replay by then, which the counted mismatch already fails.
+      def serve(state, phase, scope, node, stored, fresh, slices)
+        reads, writes, priors, mark = slices
+        live = touched(writes, priors).map { |slot, key| [slot, key, state.entry(slot, key)] }
+        state.undo(priors)
+        state.truncate_journal(mark)
+        kinds = []
+        kinds << :revalidate if state.stale_read(reads)
+        state.merge_reads(reads)
+        state.replay(writes)
+        served(state, phase, scope, node, kinds, stored, fresh, live)
+        stored
+      rescue StandardError => e
+        report(phase, scope, node, [:serve_error, "#{e.class}: #{e.message[0, 120]}"], stored, fresh, [])
+        fresh
+      end
+
+      def recompute(state, table, phase, scope, node, stored)
+        state.open_capture
+        state.open_priors
+        table.suspended += 1
+        returned = false
+        begin
+          fresh = yield
+          returned = true
+        ensure
+          table.suspended -= 1
+          priors = state.close_priors
+          refused, = state.close_capture
+          report(phase, scope, node, [:raised], stored, nil, []) unless returned
+        end
+        [fresh, priors, refused]
+      end
+
+      # Every entry the served writes or the recomputation's writes touch, each once.
+      def touched(writes, priors)
+        seen = TypingState::KeyIndex.new
+        keys = []
+        [writes, priors].each do |slice|
+          slice.each_slice(3) do |slot, key, _|
+            next if seen.key?(slot, key)
+
+            seen.store(slot, key, true)
+            keys << [slot, key]
+          end
+        end
+        keys
+      end
+
+      def served(state, phase, scope, node, kinds, stored, fresh, live) # rubocop:disable Metrics/ParameterLists
+        kinds << :type unless same?(fresh, stored)
+        diffs = live.filter_map do |slot, key, want|
+          now = state.entry(slot, key)
+          [slot, key, want, now] unless same?(want, now)
+        end
+        kinds << :table unless diffs.empty?
+        report(phase, scope, node, kinds, stored, fresh, diffs) unless kinds.empty?
+      rescue StandardError => e
+        report(phase, scope, node, [:judge_error, "#{e.class}: #{e.message[0, 120]}"], stored, fresh, [])
+      end
+    end
+  end
+end