rigortype 0.3.1 → 0.3.2

data/plugins/rigor-dry-schema/lib/rigor/plugin/dry_schema/result_shape.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Plugin
+    class DrySchema < Rigor::Plugin::Base
+      # Translates one `:dry_schema_table` entry into the `Rigor::Type::HashShape` that
+      # `SomeSchema.call(input).to_h` returns, and recognises the call chain that earns it.
+      #
+      # The table entry is the shape {SchemaScanner} publishes:
+      #
+      #     { required: { email: { type: "String", list: false } },
+      #       optional: { nickname: { type: "String", list: true } } }
+      #
+      # ## Why the shape mirrors the declaration's own vocabulary
+      #
+      # `Dry::Schema::Result#to_h` returns the *coerced input*, so on a failed validation a
+      # `required(:email)` key can be absent. Modelling that worst case — every key optional — would be
+      # the sound reading and the wrong one: the idiomatic consumer checks `success?` first, and typing
+      # `result.to_h[:age]` as `Integer?` inside that branch draws a nil diagnostic on correct code.
+      # Rigor weighs a false positive above a worst-case static reading (AGENTS.md § Implementation
+      # Guidelines), and already took the same call for RBS's `%a{implicitly-returns-nil}`.
+      #
+      # So `required` rows become required keys and `optional` rows become optional keys — the schema's
+      # own words. A reader who wrote `optional(:nickname)` is not surprised that the key reads as
+      # possibly-absent, and one who wrote `required(:email)` is not surprised that it does not.
+      #
+      # The shape is **open**: dry-schema's key map only emits declared keys, but a closed shape would
+      # turn any read of an undeclared key into a diagnostic, and being wrong there costs more than the
+      # extra precision buys.
+      module ResultShape
+        # `:bool` rows land in the published fact as "TrueClass" — the fact's vocabulary names one
+        # underlying class per row and has no union slot. A hash value typed `TrueClass` would false-fire
+        # on every `false`, so the shape widens it back to the two-class union here rather than in the
+        # fact, whose consumers (rigor-dry-struct, rigor-dry-validation) read it for a class name.
+        BOOL_CLASSES = %w[TrueClass FalseClass].freeze
+
+        module_function
+
+        # The schema constant `to_h_node`'s receiver chain names, or nil when the chain isn't the
+        # recognised `<Const>.call(...).to_h` form.
+        #
+        # Floor: the schema must be named by a constant *as written* at the call site, because the FQN is
+        # matched against the table's keys verbatim. A schema referenced through a local
+        # (`schema = NewUserSchema; schema.call(x).to_h`) or by a relative constant path from inside the
+        # declaring module resolves to no entry and contributes nothing — the pre-slice behaviour.
+        def schema_name(to_h_node)
+          return nil unless to_h_node.is_a?(Prism::CallNode) && to_h_node.name == :to_h
+          return nil unless to_h_node.arguments.nil? && to_h_node.block.nil?
+
+          inner = to_h_node.receiver
+          return nil unless inner.is_a?(Prism::CallNode) && inner.name == :call
+
+          constant_name(inner.receiver)
+        end
+
+        # The HashShape for one table entry, or nil when the schema declares no key at all. An empty open
+        # shape would be a carrier that says nothing the bare `untyped` did not already say, so declining
+        # keeps the hash's type honest about how little is known.
+        def build(entry)
+          unmodelled = entry[:unmodelled] || {}
+          required = pairs_for(entry[:required]).merge(untyped_pairs(unmodelled[:required]))
+          optional = pairs_for(entry[:optional]).merge(untyped_pairs(unmodelled[:optional]))
+          return nil if required.empty? && optional.empty?
+
+          Rigor::Type::Combinator.hash_shape_of(
+            required.merge(optional),
+            required_keys: required.keys,
+            optional_keys: optional.keys,
+            extra_keys: :open
+          )
+        end
+
+        # A key the schema declares but the scanner could not type still belongs in the shape, as
+        # `untyped`.
+        #
+        # This costs nothing at a read and buys nothing at one either — measured: with and without these
+        # entries, `payload[:address]`, `payload.fetch(:address)` and every other read infer identically,
+        # because #249 made an undeclared key on an OPEN shape read as `untyped` rather than `nil`. What
+        # it buys is the rendered shape, which is what hover and `dump_type` show: `{ email: String,
+        # address: Dynamic[top], ... }` says the schema declares `address` and Rigor cannot type it, while
+        # `{ email: String, ... }` is indistinguishable from a schema that never mentioned it — the
+        # trailing `...` only ever means "keys beyond these are permitted".
+        #
+        # It was originally load-bearing for a different reason: before #249 a key outside the shape read
+        # as `nil`, so dropping `required(:address).schema { … }` put a `call.undefined-method` on the next
+        # line of correct code. That hazard is gone; the entries stay for the honesty of the rendering.
+        def untyped_pairs(keys)
+          (keys || []).to_h { |key| [key, Rigor::Type::Combinator.untyped] }
+        end
+
+        def pairs_for(rows)
+          (rows || {}).each_with_object({}) do |(key, row), pairs|
+            type = row_type(row)
+            pairs[key] = type unless type.nil?
+          end
+        end
+
+        def row_type(row)
+          element = element_type(row[:type])
+          return nil if element.nil?
+
+          row[:list] ? Rigor::Type::Combinator.nominal_of("Array", type_args: [element]) : element
+        end
+
+        # `type` is either a class-name String (the scalar case) or a `{nested: <shape>}` Hash — an
+        # `each do ... end` element-type recursion (issue #137's ceiling slice): {SchemaScanner} already
+        # collected the nested block with the same `collect_schema_shape` algorithm a top-level schema
+        # body uses, so building its HashShape is just a recursive {.build} call.
+        def element_type(type)
+          return build(type[:nested]) if type.is_a?(Hash)
+
+          class_type(type)
+        end
+
+        def class_type(class_name)
+          return nil if class_name.nil? || class_name.empty?
+          return Rigor::Type::Combinator.union(*BOOL_CLASSES.map { |c| Rigor::Type::Combinator.nominal_of(c) }) \
+            if class_name == "TrueClass"
+
+          Rigor::Type::Combinator.nominal_of(class_name)
+        end
+
+        # Renders `Foo` / `Foo::Bar` / `::Foo::Bar` as the `::`-joined String the table is keyed by.
+        # Mirrors the helper rigor-sorbet's TypeTranslator and rigor-activerecord's ModelDiscoverer use.
+        def constant_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode then constant_path_name(node)
+          end
+        end
+
+        def constant_path_name(node)
+          parent = node.parent
+          name = node.name&.to_s
+          return nil if name.nil?
+          return name if parent.nil? # `::Foo` — the table keys are unrooted, so drop the leading `::`
+
+          prefix = constant_name(parent)
+          prefix.nil? ? nil : "#{prefix}::#{name}"
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-dry-schema/lib/rigor/plugin/dry_schema/schema_scanner.rb

@@ -67,6 +67,84 @@ module Rigor
         end
         private_class_method :scan_file
 
+        # Per-row `dry-schema.unknown-type` diagnostics (ceiling slice, issue #137). Walks an
+        # ALREADY-PARSED file's root node — the engine parses every analysed file once, so this reuses
+        # that AST rather than re-reading and re-parsing the file — collecting `{node:, key:, symbol:}`
+        # issues for a `required(:key).<verb>(:sym)` / `optional(:key).<verb>(:sym)` row whose
+        # type-bearing predicate (`filled` / `value` / `maybe` / `each`) receives a literal Symbol argument
+        # OUTSIDE `CANONICAL_TYPES`. Recurses into `each do ... end` nested rows (mirrors
+        # {#each_block_type_info}) so a nested row's bad symbol is caught too.
+        #
+        # A Constant argument (`value(Types::Email)`) is never flagged: an unresolved alias already has a
+        # silent, deliberate fallback (no `:dry_type_aliases` fact, or a name the fact doesn't know) per
+        # the existing slice-1 "drops constant-type references..." behaviour, and this diagnostic firing
+        # on it would misfire on every entirely-correct `value(Types::Email)` row in a project that simply
+        # doesn't have `rigor-dry-types` loaded.
+        #
+        # `dry-schema.unknown-predicate` (the OTHER ceiling diagnostic the README named) is deliberately
+        # NOT implemented: distinguishing a genuinely-unrecognised predicate NAME from one of dry-schema's
+        # many legitimate fine-grained predicates (`size?`, `gt?`, `format?`, `included_in?`, ...) that
+        # this scanner simply doesn't model would need a complete predicate registry this plugin doesn't
+        # have, and a `required(:key)` row with NO type-bearing predicate at all is itself entirely
+        # legitimate dry-schema (a presence-only check). Guessing here risks flagging correct code — the
+        # AGENTS.md "false positives outrank worst-case reading" call, applied by declining.
+        def unknown_type_issues(root)
+          issues = []
+          walk_for_unknown_type(root, issues)
+          issues
+        end
+
+        def walk_for_unknown_type(node, issues)
+          return if node.nil?
+
+          if node.is_a?(Prism::CallNode) && schema_entry_call?(node) && node.block
+            collect_row_issues(node.block, issues)
+          end
+          node.compact_child_nodes.each { |child| walk_for_unknown_type(child, issues) }
+        end
+        private_class_method :walk_for_unknown_type
+
+        def collect_row_issues(block_node, issues)
+          body = block_node.body
+          return if body.nil?
+
+          children = body.is_a?(Prism::StatementsNode) ? body.body : [body]
+          children.each { |child| visit_chain_for_issues(child, issues) }
+        end
+        private_class_method :collect_row_issues
+
+        def visit_chain_for_issues(node, issues)
+          return unless node.is_a?(Prism::CallNode)
+
+          key, = extract_key_and_kind(node)
+          return if key.nil?
+
+          current = node
+          while current.is_a?(Prism::CallNode)
+            if current.name == :each && current.block
+              collect_row_issues(nested_block_body(current.block), issues)
+              return
+            end
+            if TYPE_BEARING_PREDICATES.include?(current.name)
+              record_unknown_type_issue(current, key, issues)
+              return
+            end
+            current = current.receiver
+          end
+        end
+        private_class_method :visit_chain_for_issues
+
+        def record_unknown_type_issue(call_node, key, issues)
+          arg = call_node.arguments&.arguments&.first
+          return unless arg.is_a?(Prism::SymbolNode)
+
+          symbol = arg.unescaped.to_sym
+          return if CANONICAL_TYPES.key?(symbol)
+
+          issues << { node: call_node, key: key, symbol: symbol }
+        end
+        private_class_method :record_unknown_type_issue
+
         # Walks the AST collecting `<Const> = Dry::Schema.X { ... }` assignments at any nesting level.
         # Tracks the enclosing constant chain so a class-level `class Foo; SCHEMA = Dry::Schema.Params
         # { ... }; end` registers as `"Foo::SCHEMA"`.
@@ -102,7 +180,7 @@ module Rigor
           return {} unless rhs.is_a?(Prism::CallNode) && rhs.block
 
           schema_const = (qualified_prefix + [node.name.to_s]).join("::")
-          shape = collect_schema_shape(rhs.block, type_aliases)
+          shape = collect_schema_shape(rhs.block, type_aliases, nested: false)
           { schema_const => shape }
         end
         private_class_method :collect_schema_assignment
@@ -120,29 +198,51 @@ module Rigor
         end
         private_class_method :schema_entry_call?
 
-        def collect_schema_shape(block_node, type_aliases)
+        # PUBLIC reuse surface (issue #137 slices 2/3): `rigor-dry-validation`'s `params { ... }` /
+        # `json { ... }` block body is the SAME dry-schema DSL a top-level `Dry::Schema.X { ... }` body
+        # is, so that plugin delegates here instead of duplicating the required/optional walk — the
+        # `docs/design/20260517-dry-validation-slicing.md` slicing note's own "delegate to
+        # rigor-dry-schema's walker" option. Only reachable from another plugin when `rigor-dry-schema`
+        # is registered (the caller checks `Rigor::Plugin.registered_for("dry-schema")` first — that is
+        # also what makes THIS class already loaded/defined for the caller to reference).
+        #
+        # `nested:` is false at the top-level `Dry::Schema.X { ... }` body and true inside an `each do
+        # ... end` row's own recursive call (see {#each_block_type_info}). It caps the recursion at ONE
+        # level deep: with `nested: true`, {#walk_predicate_chain} declines a FURTHER `each do ... end`
+        # rather than recursing again (issue #137 deliberately does not model doubly-nested arrays of
+        # arrays). This also keeps `collect_schema_shape` from calling itself — {#each_block_type_info}
+        # is the only caller that ever passes `nested: true}` — so the call graph has no cycle for the
+        # engine's return-type inference to approximate through.
+        def collect_schema_shape(block_node, type_aliases, nested:)
           required = {}
           optional = {}
-          walk_block_body(block_node) do |kind, key, type_info|
+          declared = { required: [], optional: [] }
+          walk_block_body(block_node, type_aliases, nested) do |kind, key, type_info|
+            declared[kind] << key
             (kind == :required ? required : optional)[key] = type_info if type_info
           end
 
           remap_aliases!(required, type_aliases)
           remap_aliases!(optional, type_aliases)
 
-          { required: required.freeze, optional: optional.freeze }.freeze
+          {
+            required: required.freeze,
+            optional: optional.freeze,
+            unmodelled: unmodelled_keys(declared, required, optional)
+          }.freeze
         end
-        private_class_method :collect_schema_shape
 
         # Walks every top-level `required(:key).<predicate>(...)` / `optional(:key).<predicate>(...)`
         # chain in the block body. The block's body is either a `Prism::StatementsNode` (multi-statement)
-        # or a single expression node.
-        def walk_block_body(block_node, &)
+        # or a single expression node. `type_aliases` threads down to a nested `each do ... end` row's own
+        # recursive {#collect_schema_shape} call (slice 2's alias resolution applies at every nesting
+        # depth, not just the top level).
+        def walk_block_body(block_node, type_aliases, nested, &)
           body = block_node.body
           return if body.nil?
 
           children = body.is_a?(Prism::StatementsNode) ? body.body : [body]
-          children.each { |child| visit_chain(child, &) }
+          children.each { |child| visit_chain(child, type_aliases, nested, &) }
         end
         private_class_method :walk_block_body
 
@@ -151,13 +251,13 @@ module Rigor
         # the chain's tail. The `each(<Type>)` predicate yields a list-of-element type info (`{type: <T>,
         # list: true}`); other type-bearing predicates (`filled`/`value`/`maybe`) yield scalar info
         # (`{type: <T>, list: false}`).
-        def visit_chain(node, &block)
+        def visit_chain(node, type_aliases, nested, &block)
           return unless node.is_a?(Prism::CallNode)
 
           key, kind = extract_key_and_kind(node)
           return if key.nil?
 
-          type_info = walk_predicate_chain(node)
+          type_info = walk_predicate_chain(node, type_aliases, nested)
           block.call(kind, key, type_info)
         end
         private_class_method :visit_chain
@@ -183,9 +283,19 @@ module Rigor
         # Walks the call chain finding the first type-bearing predicate (`filled` / `value` / `maybe` /
         # `each`) and extracts its argument type. Returns a `{type:, list:}` tuple (`each` is the only
         # verb that produces a list) or nil when no recognisable type sits on the chain.
-        def walk_predicate_chain(node)
+        #
+        # `each do ... end` (a block instead of a type-symbol argument) is the ceiling's element-type
+        # recursion (issue #137): the block is itself a nested schema declaration, walked with the SAME
+        # algorithm as a top-level `Dry::Schema.X { ... }` body via {#each_block_type_info}. Already
+        # `nested` (i.e. this chain is itself inside another `each do ... end`) declines a FURTHER each —
+        # see {#collect_schema_shape}'s `nested:` doc for why the recursion caps at one level.
+        def walk_predicate_chain(node, type_aliases, nested)
           current = node
           while current.is_a?(Prism::CallNode)
+            if current.name == :each && current.block
+              return nested ? nil : each_block_type_info(current.block, type_aliases)
+            end
+
             if TYPE_BEARING_PREDICATES.include?(current.name)
               underlying = extract_type_from_predicate(current)
               return { type: underlying, list: current.name == :each } if underlying
@@ -196,6 +306,40 @@ module Rigor
         end
         private_class_method :walk_predicate_chain
 
+        # `required(:key).each do ... end` — recurses into the each-block using {#collect_schema_shape},
+        # the identical row-collection algorithm a top-level schema body uses, so a nested `required` /
+        # `optional` row gets the same predicate vocabulary, alias resolution, and untyped-row fallback as
+        # the outer schema. Two spellings are recognised: the bare `each do required(:x)...; end` form, and
+        # `each do schema do required(:x)...; end end` (dry-schema's alternate nested-hash spelling) via
+        # {#nested_block_body}.
+        #
+        # A block that yields no row at all — a bare per-element predicate like `each { int? }`, which
+        # this scanner does not model — declines (nil) rather than returning an empty nested shape: the key
+        # falls through to {#unmodelled_keys} and renders `untyped`, the same "declined, not wrong" posture
+        # every other unresolvable row already gets.
+        def each_block_type_info(each_block, type_aliases)
+          nested_shape = collect_schema_shape(nested_block_body(each_block), type_aliases, nested: true)
+          return nil if nested_shape[:required].empty? && nested_shape[:optional].empty?
+
+          { type: { nested: nested_shape }, list: true }
+        end
+        private_class_method :each_block_type_info
+
+        # Unwraps the `each do schema do ... end end` spelling to the inner `schema` block; the bare
+        # `each do required(...); ...; end` spelling passes the each-block through unchanged. Both declare
+        # the same nested key set, just at a different literal nesting depth.
+        def nested_block_body(each_block)
+          body = each_block.body
+          return each_block if body.nil?
+
+          children = body.is_a?(Prism::StatementsNode) ? body.body : [body]
+          return each_block unless children.size == 1
+
+          single = children.first
+          single.is_a?(Prism::CallNode) && single.name == :schema && single.block ? single.block : each_block
+        end
+        private_class_method :nested_block_body
+
         # Reads the first positional argument of a `filled(:string)` / `value(:integer)` /
         # `maybe(Types::Email)` call. Returns either the canonical-type-symbol's underlying class
         # ("String" / "Integer" / …), or the constant's qualified name for downstream type-alias
@@ -213,15 +357,36 @@ module Rigor
         end
         private_class_method :extract_type_from_predicate
 
+        # Keys the schema declares that this scanner saw but could not type — a predicate outside the
+        # canonical vocabulary (`filled(:not_a_type)`), a nested `schema do … end` row, or a constant
+        # alias no `:dry_type_aliases` fact resolved.
+        #
+        # They are recorded rather than forgotten so the schema's declared key set survives the scan even
+        # where its types do not. {ResultShape} puts them back into the synthesized `to_h` shape as untyped
+        # entries, which is what makes a hover read `{ email: String, address: Dynamic[top], ... }` instead
+        # of a shape indistinguishable from one that never declared `address`. Consumers that only want
+        # typed keys read `:required` / `:optional` and are unaffected.
+        def unmodelled_keys(declared, required, optional)
+          {
+            required: (declared[:required] - required.keys).uniq.freeze,
+            optional: (declared[:optional] - optional.keys).uniq.freeze
+          }.freeze
+        end
+        private_class_method :unmodelled_keys
+
         # In-place: any value's `type:` slot in `bucket` that doesn't already match a canonical class
         # (e.g. `"Types::Email"`) gets resolved through the type_aliases fact. Unresolvable values drop
         # from the bucket (no fact contribution rather than misleading data). The `list:` slot rides along
         # unchanged.
+        #
+        # A nested-shape row (`type: {nested: {...}}`, from an `each do ... end` element-type recursion)
+        # is already fully resolved by its own recursive {#collect_schema_shape} call — its `type:` slot is
+        # a Hash, not a class-name String, and is skipped here rather than treated as an unresolvable alias.
         def remap_aliases!(bucket, type_aliases)
           canonical_set = CANONICAL_TYPES.values.to_set
           bucket.each_pair.to_a.each do |key, info|
             type_name = info.fetch(:type)
-            next if canonical_set.include?(type_name)
+            next if type_name.is_a?(Hash) || canonical_set.include?(type_name)
 
             resolved = type_aliases[type_name]
             if resolved

data/plugins/rigor-dry-schema/lib/rigor/plugin/dry_schema.rb

@@ -5,6 +5,7 @@ require "prism"
 require "rigor/plugin"
 
 require_relative "dry_schema/schema_scanner"
+require_relative "dry_schema/result_shape"
 
 module Rigor
   module Plugin
@@ -58,14 +59,22 @@ module Rigor
     #   above.
     # - Publishes the table; no user-facing diagnostics yet.
     #
-    # The **ceiling** (slice 2+):
+    # Landed since: typed `result.to_h` returns, via the {.dynamic_return} rule below rather than the
+    # ADR-16 Tier C substrate the README originally projected — Tier C synthesises methods on a class
+    # from a class-level DSL call, and this is a return type for a call chain off a constant.
     #
-    # - Synthesise typed `result.to_h` returns from each schema via ADR-16 Tier C heredoc-template
-    #   substrate.
-    # - Nested schemas (`schema(do ... end)` inside another row).
-    # - `predicates(:size?)` / `each { ... }` recursion.
-    # - Per-row `dry-schema.unknown-predicate` / `dry-schema.unknown-type` `:info` diagnostics when a
-    #   row's predicate or type symbol isn't recognised.
+    # Landed since (issue #137): `each do ... end` element-type recursion ({SchemaScanner#each_block_type_info})
+    # and the `dry-schema.unknown-type` `:info` diagnostic ({SchemaScanner#unknown_type_issues}), wired
+    # below via {.node_file_context} + {.node_rule}.
+    #
+    # The **ceiling** (still open):
+    #
+    # - Nested schemas OUTSIDE an `each` (`required(:x).schema do ... end` with no `each` in the chain) —
+    #   the key is still kept as untyped; only the `each`-wrapped nested form recurses.
+    # - `predicates(:size?)` / other fine-grained predicate constraint walks.
+    # - `dry-schema.unknown-predicate` — deliberately NOT shipped; see {SchemaScanner.unknown_type_issues}
+    #   for why (no reliable static signal without a full predicate registry; risks flagging correct code).
+    # - `rigor-dry-validation` integration — landed separately in that plugin's own slices 2/3 (issue #137).
     class DrySchema < Rigor::Plugin::Base
       manifest(
         id: "dry-schema",
@@ -76,6 +85,46 @@ module Rigor
         consumes: [{ plugin_id: "dry-types", name: :dry_type_aliases, optional: true }]
       )
 
+      # ADR-37 dynamic return — `NewUserSchema.call(input).to_h` yields the schema's own
+      # `HashShape[{email: String, ?nickname: String}]` instead of the untyped hash the DSL's boundary
+      # otherwise leaves behind. The shape's required/optional split and its open extra-key policy are
+      # argued in {ResultShape}.
+      #
+      # Gated on the method name alone, not on a `Dry::Schema::Result` receiver: this plugin ships no RBS
+      # overlay for dry-schema, so in an ordinary project the receiver of `.to_h` is untyped and a
+      # `receivers:` gate would never fire. The cost of the wider gate is bounded — the engine compiles
+      # `methods:` into its registry name gate, so the block is consulted only for `.to_h` calls, and its
+      # first act rejects any chain that is not `<Const>.call(...).to_h` before the table is touched.
+      dynamic_return methods: [:to_h] do |call_node, _scope|
+        result_shape_for(call_node)
+      end
+
+      # ADR-37 slice 1c two-pass: the "collect" half of `dry-schema.unknown-type` (issue #137's ceiling
+      # diagnostic). Walks the already-parsed file root once via {SchemaScanner.unknown_type_issues}; the
+      # `node_rule` below is the "validate" half that turns each collected issue into a Diagnostic.
+      node_file_context do |root, _scope|
+        SchemaScanner.unknown_type_issues(root)
+      end
+
+      # Fires exactly once per file: `Prism::ProgramNode` is the AST root, and the engine's node walker
+      # visits the root itself before descending (see `Source::NodeWalker#walk_with_ancestors`). Cheaper
+      # than a `Prism::CallNode` rule re-matching every call site in the file — the collect pass already
+      # did the real walk.
+      node_rule Prism::ProgramNode do |_node, _scope, path, issues|
+        next [] if issues.nil? || issues.empty?
+
+        issues.map do |issue|
+          diagnostic(
+            issue[:node],
+            path: path,
+            message: "`#{issue[:key]}` uses `:#{issue[:symbol]}`, which is not a recognised dry-schema " \
+                     "canonical type symbol (see the plugin README's predicate type table)",
+            severity: :info,
+            rule: "dry-schema.unknown-type"
+          )
+        end
+      end
+
       # Walks every project file once during `prepare(services)` to build the schema table, then publishes
       # via the ADR-9 fact store. Mirrors the rigor-dry-types `#prepare` shape — the walk is bounded by
       # `paths:`, parse errors degrade silently.
@@ -93,10 +142,28 @@ module Rigor
 
       def init(_services)
         @scannable_paths = nil
+        @result_shapes = {}
       end
 
       private
 
+      # The HashShape for a `<Const>.call(...).to_h` chain, or nil when the chain isn't that shape, names
+      # no schema in the table, or names one that declares no key.
+      # Memoised per schema name INCLUDING nil: a carrier is a value object, and the miss is the common
+      # case on any project that calls `to_h` on something that isn't a schema result.
+      def result_shape_for(call_node)
+        name = ResultShape.schema_name(call_node)
+        return nil if name.nil?
+
+        # `||=` rather than a plain read of an `init`-assigned ivar: `dynamic_return_type` rescues every
+        # StandardError to nil, so a NoMethodError here would turn the whole feature off in silence.
+        shapes = (@result_shapes ||= {})
+        return shapes[name] if shapes.key?(name)
+
+        entry = read_fact(plugin_id: manifest.id, name: :dry_schema_table)&.[](name)
+        shapes[name] = entry.nil? ? nil : ResultShape.build(entry)
+      end
+
       def scannable_paths(services)
         @scannable_paths ||= services.configuration.paths.flat_map do |entry|
           if File.directory?(entry)