rigortype 0.1.4 → 0.1.6

data/lib/rigor/plugin/manifest.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../inference/hkt_registry"
+
 module Rigor
   module Plugin
     # Value object describing one plugin's identity and metadata.
@@ -11,7 +13,7 @@ module Rigor
     # The fields are pinned by ADR-2 § "Registration, Configuration,
     # and Caching"; the v0.1.0 plugin contract surface treats this
     # struct as the public manifest shape.
-    class Manifest
+    class Manifest # rubocop:disable Metrics/ClassLength
       # Same regex {Rigor::Cache::Store::VALID_PRODUCER_ID} uses,
       # so plugin ids round-trip through cache producer ids and
       # `plugin.<id>.<rule>` diagnostic identifiers without escape.
@@ -38,12 +40,15 @@ module Rigor
       end
 
       attr_reader :id, :version, :description, :protocols, :config_schema, :produces, :consumes,
-                  :owns_receivers, :type_node_resolvers
+                  :owns_receivers, :type_node_resolvers, :block_as_methods, :heredoc_templates,
+                  :trait_registries, :external_files, :hkt_registrations, :hkt_definitions
 
       def initialize( # rubocop:disable Metrics/ParameterLists
         id:, version:,
         description: nil, protocols: [], config_schema: {},
-        produces: [], consumes: [], owns_receivers: [], type_node_resolvers: []
+        produces: [], consumes: [], owns_receivers: [], type_node_resolvers: [],
+        block_as_methods: [], heredoc_templates: [], trait_registries: [], external_files: [],
+        hkt_registrations: [], hkt_definitions: []
       )
         validate_id!(id)
         validate_version!(version)
@@ -52,17 +57,25 @@ module Rigor
         validate_produces!(produces)
         validate_owns_receivers!(owns_receivers)
         validate_type_node_resolvers!(type_node_resolvers)
+        validate_block_as_methods!(block_as_methods)
+        validate_heredoc_templates!(heredoc_templates)
+        validate_trait_registries!(trait_registries)
+        validate_external_files!(external_files)
+        validate_hkt_registrations!(hkt_registrations)
+        validate_hkt_definitions!(hkt_definitions)
 
         assign_fields(id, version, description, protocols, config_schema, produces, consumes, owns_receivers,
-                      type_node_resolvers)
+                      type_node_resolvers, block_as_methods, heredoc_templates, trait_registries, external_files,
+                      hkt_registrations, hkt_definitions)
         freeze
       end
 
       private
 
-      # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize
       def assign_fields(id, version, description, protocols, config_schema, produces, consumes, owns_receivers,
-                        type_node_resolvers)
+                        type_node_resolvers, block_as_methods, heredoc_templates, trait_registries, external_files,
+                        hkt_registrations, hkt_definitions)
         @id = id.dup.freeze
         @version = version.dup.freeze
         @description = description.nil? ? nil : description.to_s.dup.freeze
@@ -72,8 +85,14 @@ module Rigor
         @consumes = coerce_consumes(consumes)
         @owns_receivers = owns_receivers.map { |c| c.to_s.dup.freeze }.freeze
         @type_node_resolvers = type_node_resolvers.dup.freeze
+        @block_as_methods = block_as_methods.dup.freeze
+        @heredoc_templates = heredoc_templates.dup.freeze
+        @trait_registries = trait_registries.dup.freeze
+        @external_files = external_files.dup.freeze
+        @hkt_registrations = hkt_registrations.dup.freeze
+        @hkt_definitions = hkt_definitions.dup.freeze
       end
-      # rubocop:enable Metrics/ParameterLists
+      # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize
 
       public
 
@@ -100,7 +119,7 @@ module Rigor
         errors
       end
 
-      def to_h
+      def to_h # rubocop:disable Metrics/AbcSize
         {
           "id" => id,
           "version" => version,
@@ -110,7 +129,13 @@ module Rigor
           "produces" => produces.map(&:to_s),
           "consumes" => consumes.map { |c| consumption_hash(c) },
           "owns_receivers" => owns_receivers,
-          "type_node_resolvers" => type_node_resolvers.map { |r| r.class.name }
+          "type_node_resolvers" => type_node_resolvers.map { |r| r.class.name },
+          "block_as_methods" => block_as_methods.map(&:to_h),
+          "heredoc_templates" => heredoc_templates.map(&:to_h),
+          "trait_registries" => trait_registries.map(&:to_h),
+          "external_files" => external_files.map(&:to_h),
+          "hkt_registrations" => hkt_registrations.map(&:to_h),
+          "hkt_definitions" => hkt_definitions.map { |d| { "uri" => d.uri, "params" => d.params } }
         }
       end
 
@@ -208,6 +233,99 @@ module Rigor
               "Rigor::Plugin::TypeNodeResolver instances, got #{resolvers.inspect}"
       end
 
+      # ADR-16 slice 1a — `block_as_methods:` declares the Tier A
+      # substrate entries the plugin contributes. Slice 1a carries
+      # the declarations on the manifest; the engine hook that
+      # actually narrows `Scope#self_type` for matching blocks
+      # arrives in a subsequent slice.
+      def validate_block_as_methods!(entries)
+        return if entries.is_a?(Array) && entries.all?(Macro::BlockAsMethod)
+
+        raise ArgumentError,
+              "plugin manifest block_as_methods must be an Array of " \
+              "Rigor::Plugin::Macro::BlockAsMethod instances, got #{entries.inspect}"
+      end
+
+      # ADR-16 slice 2a — `heredoc_templates:` declares the Tier C
+      # substrate entries (heredoc-template synthesis on class-level
+      # DSL calls). Slice 2a carries the declarations on the
+      # manifest; the pre-pass + `SyntheticMethodIndex` that actually
+      # emit synthetic methods arrive in slice 2b.
+      def validate_heredoc_templates!(entries)
+        return if entries.is_a?(Array) && entries.all?(Macro::HeredocTemplate)
+
+        raise ArgumentError,
+              "plugin manifest heredoc_templates must be an Array of " \
+              "Rigor::Plugin::Macro::HeredocTemplate instances, got #{entries.inspect}"
+      end
+
+      # ADR-16 slice 3a — `trait_registries:` declares the Tier B
+      # substrate entries (trait-inlining via bundled module
+      # registry). Slice 3a carries the declarations on the
+      # manifest; the scanner + per-method explosion through
+      # `SyntheticMethodIndex` (slice 2b primitive) arrives in
+      # slice 3b.
+      def validate_trait_registries!(entries)
+        return if entries.is_a?(Array) && entries.all?(Macro::TraitRegistry)
+
+        raise ArgumentError,
+              "plugin manifest trait_registries must be an Array of " \
+              "Rigor::Plugin::Macro::TraitRegistry instances, got #{entries.inspect}"
+      end
+
+      # ADR-16 slice 5a — `external_files:` declares the Tier D
+      # substrate entries (external-Ruby-file inclusion under a
+      # declared `self`). Slice 5a carries the declarations on
+      # the manifest; the engine integration that walks the
+      # matched files + narrows their entry scope is **queued for
+      # slice 5b**, gated on demonstrated demand from concrete
+      # plugin targets (Redmine webhook payloads, tDiary plugin
+      # loader, etc.). Plugin authors MAY declare entries today;
+      # the substrate does not yet act on them.
+      def validate_external_files!(entries)
+        return if entries.is_a?(Array) && entries.all?(Macro::ExternalFile)
+
+        raise ArgumentError,
+              "plugin manifest external_files must be an Array of " \
+              "Rigor::Plugin::Macro::ExternalFile instances, got #{entries.inspect}"
+      end
+
+      # ADR-20 slice 6 — `hkt_registrations:` declares the
+      # Lightweight HKT URI registrations this plugin ships
+      # (analogous to `%a{rigor:v1:hkt_register: ...}` directives
+      # but published via the manifest contract instead of a
+      # shipped `.rbs` file). Each entry MUST be an
+      # `Rigor::Inference::HktRegistry::Registration`. The
+      # registry aggregator on `Plugin::Registry` flattens
+      # entries from every loaded plugin and merges them into
+      # `env.hkt_registry` on top of `Builtins::HktBuiltins.registry`;
+      # user `.rbs` overlays merge on top of plugin entries
+      # last-write-wins.
+      def validate_hkt_registrations!(entries)
+        return if entries.is_a?(Array) && entries.all?(Inference::HktRegistry::Registration)
+
+        raise ArgumentError,
+              "plugin manifest hkt_registrations must be an Array of " \
+              "Rigor::Inference::HktRegistry::Registration instances, got #{entries.inspect}"
+      end
+
+      # ADR-20 slice 6 — `hkt_definitions:` declares the
+      # plugin's HKT type-function bodies (analogous to
+      # `%a{rigor:v1:hkt_define: ...}` directives). Each entry
+      # MUST be an `Rigor::Inference::HktRegistry::Definition`
+      # — typically built via
+      # `Rigor::Inference::HktRegistry.definition_with_body_tree(...)`
+      # so plugin authors can build the body programmatically
+      # via {Rigor::Inference::HktBody}'s node-constructor API
+      # without parsing a string.
+      def validate_hkt_definitions!(entries)
+        return if entries.is_a?(Array) && entries.all?(Inference::HktRegistry::Definition)
+
+        raise ArgumentError,
+              "plugin manifest hkt_definitions must be an Array of " \
+              "Rigor::Inference::HktRegistry::Definition instances, got #{entries.inspect}"
+      end
+
       def coerce_consumes(consumes)
         unless consumes.is_a?(Array)
           raise ArgumentError, "plugin manifest consumes must be an Array, got #{consumes.inspect}"

data/lib/rigor/plugin/registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "blueprint"
+
 module Rigor
   module Plugin
     # Read-side query API over the plugins loaded for a single
@@ -13,20 +15,48 @@ module Rigor
     # the order in which {Rigor::Plugin::Loader} resolved
     # configuration entries, which is project-config order with
     # plugin-id alphabetical as the tie-breaker.
+    #
+    # ADR-15 Phase 3 — alongside the instantiated `plugins`, the
+    # registry carries `blueprints`: a frozen, Ractor-shareable
+    # `Array<Blueprint>` that records how to re-instantiate the
+    # same plugin set in a worker Ractor. The eventual Phase 4
+    # pool ships `blueprints` across the boundary and calls
+    # {.materialize} per-Ractor; the live `plugins` carriage on
+    # the coordinator registry stays unchanged.
     class Registry
-      attr_reader :plugins, :load_errors
+      attr_reader :plugins, :load_errors, :blueprints
 
       # @param plugins [Array<Rigor::Plugin::Base>] instantiated
       #   plugin instances in deterministic order.
       # @param load_errors [Array<Rigor::Plugin::LoadError>] failures
       #   surfaced during loading. Each error is also turned into a
       #   diagnostic by the runner.
-      def initialize(plugins: [], load_errors: [])
+      # @param blueprints [Array<Rigor::Plugin::Blueprint>] frozen,
+      #   Ractor-shareable replay descriptors aligned 1:1 with
+      #   `plugins`. The loader fills this in; callers that
+      #   construct Registry manually MAY pass `[]` and accept
+      #   that {.materialize} cannot replay the set.
+      def initialize(plugins: [], load_errors: [], blueprints: [])
         @plugins = plugins.dup.freeze
         @load_errors = load_errors.dup.freeze
+        @blueprints = blueprints.dup.freeze
         freeze
       end
 
+      # ADR-15 Phase 3 — build a fresh Registry from the supplied
+      # blueprint set by replaying {Blueprint#materialize} per
+      # entry against `services`. The returned registry carries
+      # NEW plugin instances (mutable per-Ractor accumulators
+      # included) and the same blueprint set, so a worker can
+      # hand the materialised registry to Environment without
+      # losing the replay handle. `load_errors` is intentionally
+      # empty: load-time failures already surfaced in the
+      # coordinator registry and don't repeat per worker.
+      def self.materialize(blueprints:, services:)
+        plugins = blueprints.map { |bp| bp.materialize(services: services) }
+        new(plugins: plugins, blueprints: blueprints, load_errors: [])
+      end
+
       def find(id)
         id_s = id.to_s
         plugins.find { |plugin| plugin.manifest.id == id_s }
@@ -55,6 +85,25 @@ module Rigor
         plugins.flat_map { |plugin| plugin.manifest.type_node_resolvers }
       end
 
+      # ADR-20 slice 6 — aggregate every loaded plugin's
+      # manifest-declared HKT registrations + definitions
+      # into a single `Inference::HktRegistry` overlay that
+      # `Environment#hkt_registry` merges on top of the
+      # bundled `Builtins::HktBuiltins.registry`. Last
+      # plugin to register a URI wins (registration order
+      # determined by the user's `plugins:` list); user
+      # `.rbs` overlays merge on top of this overlay last.
+      # Returns `Inference::HktRegistry::EMPTY` when no
+      # plugin contributes HKT entries so callers can skip
+      # the merge.
+      def hkt_overlay_registry
+        registrations = plugins.flat_map { |plugin| plugin.manifest.hkt_registrations }
+        definitions = plugins.flat_map { |plugin| plugin.manifest.hkt_definitions }
+        return Inference::HktRegistry::EMPTY if registrations.empty? && definitions.empty?
+
+        Inference::HktRegistry.new(registrations: registrations, definitions: definitions)
+      end
+
       EMPTY = new.freeze
     end
   end

data/lib/rigor/plugin.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "plugin/type_node_resolver"
+require_relative "plugin/macro"
 require_relative "plugin/manifest"
 require_relative "plugin/access_denied_error"
 require_relative "plugin/trust_policy"

data/lib/rigor/rbs_extended/hkt_directives.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require_relative "../inference/hkt_registry"
+require_relative "../inference/hkt_body_parser"
+
+module Rigor
+  module RbsExtended
+    # ADR-20 § "Decision D6" parser for the two new HKT
+    # directives that live in `.rbs` files at module / class
+    # scope:
+    #
+    # - `%a{rigor:v1:hkt_register: uri=<uri> arity=<int>
+    #   variance=<v1>,<v2>,... bound=<class_name_or_untyped>}` —
+    #   registers a defunctionalised type-constructor URI
+    #   together with its arity, per-position variance, and
+    #   erasure bound.
+    # - `%a{rigor:v1:hkt_define: uri=<uri> params=<P1>,<P2>,...
+    #   body=<body_text>}` — binds the URI to a type-function
+    #   body that {HktBodyParser} parses into an
+    #   {HktBody::Union} tree.
+    #
+    # ## Payload format
+    #
+    # **Space-separated `key=value` pairs.** The format is
+    # constrained by RBS's `%a{...}` annotation grammar, which
+    # does NOT accept arbitrary nested punctuation (a JSON
+    # payload with quotes / nested braces will fail RBS
+    # parsing). Each value is a bare token: no quoting, no
+    # escaping. Values that contain spaces or `=` signs MUST
+    # be encoded via the `body=` key, which is special-cased
+    # to gobble everything from `body=` to the end of the
+    # payload — see `parse_define`.
+    #
+    # Example annotations (write inside a class / module
+    # declaration so the annotation attaches to the decl
+    # RBS parses):
+    #
+    #   %a{rigor:v1:hkt_register: uri=json::value arity=1
+    #     variance=out bound=untyped}
+    #   %a{rigor:v1:hkt_define: uri=json::value params=K
+    #     body=nil | true | false | Integer | Float | String |
+    #          Array[App[json::value, K]] |
+    #          Hash[K, App[json::value, K]]}
+    #   module JsonOverlay
+    #   end
+    #
+    # ## Bound vocabulary
+    #
+    # - `untyped` resolves to `Rigor::Type::Combinator.untyped`
+    #   (i.e. `Dynamic[Top]`, the ADR-20 WD2 default).
+    # - A bare class name (`String`, `Integer`, …) resolves
+    #   through `name_scope.nominal_for_name(...)` when
+    #   supplied, falling back to a raw `Rigor::Type::Nominal`
+    #   otherwise.
+    # - Anything else falls back to `untyped` and emits an
+    #   `:info` diagnostic via the supplied reporter (fail-soft
+    #   so an unrecognised bound never crashes the loader).
+    #
+    # Richer bound forms (parameterised generics, unions,
+    # refinements) wait for a follow-up slice's expression
+    # parser.
+    module HktDirectives
+      module_function
+
+      REGISTER_DIRECTIVE = "rigor:v1:hkt_register:"
+      DEFINE_DIRECTIVE   = "rigor:v1:hkt_define:"
+
+      DEFAULT_VARIANCE = :inv
+      DEFAULT_BOUND_LITERAL = "untyped"
+
+      # Parses one `%a{rigor:v1:hkt_register: ...}` payload
+      # string and returns a `Registration`, or `nil` when the
+      # string is not an hkt_register directive (so callers can
+      # walk a list of annotations without each having to
+      # pre-filter).
+      def parse_register(string, name_scope: nil, reporter: nil, source_location: nil)
+        payload = extract_payload(string, REGISTER_DIRECTIVE)
+        return nil if payload.nil?
+
+        kvs = parse_kv_payload(payload, body_key: nil)
+
+        uri = symbolize_uri(kvs["uri"], reporter: reporter, source_location: source_location)
+        return nil if uri.nil?
+
+        arity = coerce_arity(kvs["arity"], reporter: reporter, source_location: source_location)
+        return nil if arity.nil?
+
+        variance = coerce_variance(kvs["variance"], arity, reporter: reporter, source_location: source_location)
+        return nil if variance.nil?
+
+        bound = resolve_bound(
+          kvs["bound"] || DEFAULT_BOUND_LITERAL,
+          name_scope: name_scope,
+          reporter: reporter,
+          source_location: source_location
+        )
+
+        Inference::HktRegistry::Registration.new(
+          uri: uri,
+          arity: arity,
+          variance: variance,
+          bound: bound
+        )
+      rescue ArgumentError => e
+        record_hkt_error(reporter, "hkt_register: #{e.message}", source_location)
+        nil
+      end
+
+      # Parses one `%a{rigor:v1:hkt_define: ...}` payload
+      # string and returns a `Definition`, or `nil` when the
+      # string is not an hkt_define directive.
+      def parse_define(string, reporter: nil, source_location: nil)
+        payload = extract_payload(string, DEFINE_DIRECTIVE)
+        return nil if payload.nil?
+
+        kvs = parse_kv_payload(payload, body_key: "body")
+
+        uri = symbolize_uri(kvs["uri"], reporter: reporter, source_location: source_location)
+        return nil if uri.nil?
+
+        params = coerce_params(kvs["params"], reporter: reporter, source_location: source_location)
+        return nil if params.nil?
+
+        body = kvs["body"]
+        unless body.is_a?(String)
+          record_hkt_error(reporter, "hkt_define: missing body=", source_location)
+          return nil
+        end
+
+        body_tree = parse_body_tree(body, params, reporter: reporter, source_location: source_location)
+
+        Inference::HktRegistry::Definition.new(
+          uri: uri,
+          params: params,
+          body: body,
+          body_tree: body_tree,
+          source_path: source_path_of(source_location),
+          source_line: source_line_of(source_location)
+        )
+      rescue ArgumentError => e
+        record_hkt_error(reporter, "hkt_define: #{e.message}", source_location)
+        nil
+      end
+
+      def extract_payload(string, directive)
+        return nil if string.nil?
+
+        idx = string.index(directive)
+        return nil if idx.nil?
+
+        payload = string[(idx + directive.size)..].to_s.strip
+        # Strip trailing `}` of the wrapping `%a{...}` form if
+        # the caller passed the raw annotation string. The
+        # parser also accepts a pre-extracted payload.
+        payload = payload.sub(/\}\z/, "") if payload.end_with?("}") && !balanced_braces?(payload)
+        payload.empty? ? nil : payload
+      end
+
+      def balanced_braces?(string)
+        depth = 0
+        string.each_char do |ch|
+          case ch
+          when "{" then depth += 1
+          when "}"
+            depth -= 1
+            return false if depth.negative?
+          end
+        end
+        depth.zero?
+      end
+
+      # Parses a space-separated `key=value [key=value ...]`
+      # payload into a Hash. When `body_key` is supplied AND
+      # that key appears, everything from `<body_key>=` to
+      # the end of the payload becomes the value (body
+      # contents typically include spaces, `|`, `[]` etc.
+      # that the simple tokenizer cannot otherwise carry).
+      KV_KEY_PATTERN = /(?<![\w.])([a-z_]\w*)=/
+      private_constant :KV_KEY_PATTERN
+
+      def parse_kv_payload(payload, body_key:)
+        result = {}
+        # Find every `<key>=` boundary; each value runs to
+        # the next boundary or end of string.
+        markers = []
+        payload.scan(KV_KEY_PATTERN) { markers << [::Regexp.last_match[1], ::Regexp.last_match.end(0)] }
+        markers.each_with_index do |(key, value_start), i|
+          if body_key && key == body_key
+            result[key] = payload[value_start..].to_s.strip
+            break
+          end
+
+          value_end = markers[i + 1] ? markers[i + 1][1] - markers[i + 1][0].size - 1 : payload.size
+          result[key] = payload[value_start...value_end].to_s.strip
+        end
+        result
+      end
+
+      # ADR-20 slice 2b — parse the body String into an
+      # `HktBody::*` tree via {Inference::HktBodyParser.parse}.
+      # On parse failure: emit a fail-soft `:info` reporter
+      # entry and return `nil` so the resulting Definition
+      # keeps its `body` String slot but `body_tree` stays
+      # absent (the reducer falls back to `app.bound` at call
+      # time per ADR-20 D5).
+      def parse_body_tree(body, params, reporter:, source_location:)
+        return nil if body.nil? || body.empty?
+
+        Inference::HktBodyParser.parse(body, params: params)
+      rescue Inference::HktBodyParser::ParseError => e
+        record_hkt_error(reporter, "hkt_define body parse error: #{e.message}", source_location)
+        nil
+      rescue ArgumentError => e
+        record_hkt_error(reporter, "hkt_define body construction error: #{e.message}", source_location)
+        nil
+      end
+
+      def symbolize_uri(raw, reporter:, source_location:)
+        if raw.nil? || raw.empty?
+          record_hkt_error(reporter, "uri= is required", source_location)
+          return nil
+        end
+        unless raw.include?(Type::App::URI_SEPARATOR)
+          record_hkt_error(
+            reporter,
+            "uri must be namespaced as `a::b` per ADR-20 WD1, got #{raw.inspect}",
+            source_location
+          )
+          return nil
+        end
+
+        raw.to_sym
+      end
+
+      def coerce_arity(raw, reporter:, source_location:)
+        if raw && /\A\d+\z/.match?(raw) && raw.to_i.positive?
+          raw.to_i
+        else
+          record_hkt_error(reporter, "arity must be a positive Integer, got #{raw.inspect}", source_location)
+          nil
+        end
+      end
+
+      def coerce_variance(raw, arity, reporter:, source_location:)
+        # Omitted variance defaults to `[:inv] * arity` per ADR-20 WD4.
+        variance =
+          if raw.nil? || raw.empty?
+            Array.new(arity, DEFAULT_VARIANCE)
+          else
+            raw.split(",").map { |v| v.strip.to_sym }
+          end
+
+        unless variance.size == arity
+          record_hkt_error(reporter, "variance length #{variance.size} does not match arity #{arity}", source_location)
+          return nil
+        end
+
+        unless variance.all? { |v| %i[out in inv].include?(v) }
+          record_hkt_error(
+            reporter,
+            "variance entries must be `out` / `in` / `inv`, got #{variance.inspect}",
+            source_location
+          )
+          return nil
+        end
+
+        variance
+      end
+
+      def coerce_params(raw, reporter:, source_location:)
+        if raw.nil? || raw.empty?
+          record_hkt_error(reporter, "params= is required (comma-separated UCName list)", source_location)
+          return nil
+        end
+
+        raw.split(",").map { |p| p.strip.to_sym }
+      end
+
+      def resolve_bound(raw, name_scope:, reporter:, source_location:)
+        return Type::Combinator.untyped if raw.nil? || raw.strip.empty?
+        return Type::Combinator.untyped if raw.strip == DEFAULT_BOUND_LITERAL
+
+        class_name = raw.strip
+        if /\A(?:::)?(?:[A-Z]\w*)(?:::[A-Z]\w*)*\z/.match?(class_name)
+          normalized = class_name.sub(/\A::/, "")
+          return Type::Nominal.new(normalized) if name_scope.nil?
+
+          if name_scope.respond_to?(:nominal_for_name)
+            resolved = name_scope.nominal_for_name(normalized)
+            return resolved if resolved
+          end
+          return Type::Nominal.new(normalized)
+        end
+
+        record_hkt_error(
+          reporter,
+          "bound `#{raw}` not recognised (accepts `untyped` or a bare class name); falling back to `untyped`",
+          source_location
+        )
+        Type::Combinator.untyped
+      end
+
+      def source_path_of(source_location)
+        return nil if source_location.nil?
+
+        source_location.respond_to?(:name) ? source_location.name : nil
+      end
+
+      def source_line_of(source_location)
+        return nil if source_location.nil?
+
+        source_location.respond_to?(:start_line) ? source_location.start_line : nil
+      end
+
+      def record_hkt_error(reporter, message, source_location)
+        return if reporter.nil?
+
+        if reporter.respond_to?(:record)
+          reporter.record(directive: "hkt", message: message, source_location: source_location)
+        elsif reporter.respond_to?(:<<)
+          reporter << { directive: "hkt", message: message, source_location: source_location }
+        end
+      end
+    end
+  end
+end