necropsy 0.2.0 → 0.3.0

data/lib/necropsy/runner.rb

@@ -1,48 +1,265 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Necropsy
   class Runner
-    attr_reader :root, :config, :analyzers
+    ANALYZER_ERROR_MESSAGE_BYTES = 500
+    INVALID_BLOCKER_KINDS = %i[
+      analyzer_failure blocker_invalid evidence_collision rails_route_health resolution_invalid unsound_rta_pruning
+    ].freeze
+    DEGRADED_BLOCKER_KINDS = %i[
+      reference_scan_incomplete reference_scope_incomplete source_discovery_incomplete
+    ].freeze
+
+    attr_reader :root, :config, :analyzers, :ignored_reference_paths, :clock
 
-    def initialize(root:, config_path: nil, analyzers: nil)
+    def initialize(root:, config_path: nil, analyzers: nil, ignored_reference_paths: [], as_of: nil)
       @root = File.expand_path(root)
       @config = Configuration.load(root: @root, path: config_path)
       @analyzers = analyzers
+      @ignored_reference_paths = ignored_reference_paths
+      @clock = Clock.new(as_of: as_of)
     end
 
-    def analyze
-      project = Project.new(root: root, config: config)
-      graph = CallGraph.new(project.scan_result, ambiguity_limit: config.ambiguity_limit)
+    def analyze(rta_pruning: config.rta_pruning, profile: false)
+      rta_pruning = normalize_rta_pruning(rta_pruning)
+      profiler = profile ? PerformanceProfiler.new : nil
+      project = measure_phase(profiler, 'project') { Project.new(root: root, config: config) }
+      source_snapshot = measure_phase(profiler, 'source_snapshot') { project.source_snapshot }
+      graph = measure_phase(profiler, 'scan') do
+        CallGraph.new(project.scan_result, ambiguity_limit: config.ambiguity_limit)
+      end
+      project.scope_blockers.each { |blocker| graph.add_blocker(blocker) }
+      graph.add_blocker(unsound_rta_pruning_blocker) if rta_pruning == :legacy
       rta_results = []
 
-      apply_entry_points(graph, project)
-      configured_analyzers.each do |analyzer|
-        graph.add_profile(analyzer.profile)
-        result = analyzer.analyze(graph, project)
-        graph.apply_result(result)
-        rta_results << result if analyzer.profile.name == :rta
+      measure_phase(profiler, 'entry_points') { apply_entry_points(graph, project) }
+      configured_analyzers.each do |configured_analyzer|
+        analyzer_name = configured_analyzer.profile.name
+        analyzer_profile, result = measure_phase(profiler, "analyzer:#{analyzer_name}") do
+          run_analyzer(graph, project, configured_analyzer, rta_pruning)
+        end
+        rta_results << result if analyzer_profile&.name == :rta && result
+      end
+      graph.refresh_derived_state
+      measure_phase(profiler, 'reachability') do
+        rta_results.each { |result| graph.reconcile_rta_result(result) } if rta_pruning == :legacy
       end
-      rta_results.each { |result| graph.reconcile_rta_result(result) }
 
-      reachability = Reachability::Engine.new(graph).call
-      findings = Confidence::Scorer.new(graph: graph, reachability: reachability, project: project).findings
+      reachability = measure_phase(profiler, 'reachability_engine') { Reachability::Engine.new(graph).call }
+      LoadGraph.record_unrooted_units(graph: graph, reachability: reachability)
+      findings = measure_phase(profiler, 'scoring') do
+        scorer = Confidence::Scorer.new(graph: graph, reachability: reachability, project: project, clock: clock)
+        scorer.findings
+      end
+      barrier_matches = measure_phase(profiler, 'reference_barrier') do
+        ReferenceBarrier.new(
+          graph: graph,
+          project: project,
+          ignored_paths: ignored_reference_paths
+        ).apply(findings)
+      end
+      if barrier_matches.positive?
+        findings = Confidence::Scorer.new(
+          graph: graph, reachability: reachability, project: project, clock: clock
+        ).findings
+      end
+      final_source_snapshot = measure_phase(profiler, 'source_snapshot_verification') { project.fresh_source_snapshot }
+      analysis_health = build_analysis_health(graph, source_snapshot, final_source_snapshot)
+      source_snapshot = verified_source_snapshot(source_snapshot, final_source_snapshot)
+      performance = profiler&.report(
+        counts: graph.performance_counts,
+        report_index_size_bytes: report_index_size_bytes(graph)
+      )
       Report.new(
         root: root,
         graph: graph,
         findings: findings,
         reachability: reachability,
+        project: project,
+        source_snapshot: source_snapshot,
+        analysis_health: analysis_health,
         report_include_paths: config.report_include_paths,
-        report_exclude_paths: config.report_exclude_paths
+        report_exclude_paths: config.report_exclude_paths,
+        performance_profile: performance
       )
     end
 
     private
 
+    def build_analysis_health(graph, initial_snapshot, final_snapshot)
+      reasons = snapshot_health_reasons(initial_snapshot, final_snapshot)
+      graph.blockers.each do |blocker|
+        severity = blocker_health_severity(blocker)
+        next unless severity
+
+        reasons << blocker_health_reason(blocker, severity)
+      end
+      AnalysisHealth.from_reasons(reasons.uniq { |reason| BoundedCanonicalizer.dump(reason) })
+    end
+
+    def snapshot_health_reasons(initial_snapshot, final_snapshot)
+      snapshots = { 'initial' => initial_snapshot, 'final' => final_snapshot }
+      unavailable = snapshots.filter_map do |phase, snapshot|
+        next if snapshot['status'] == 'complete'
+
+        { 'phase' => phase, 'reason' => snapshot['reason'], 'details' => snapshot.except('sha256') }
+      end
+      return [{ 'severity' => 'invalid', 'code' => 'source_snapshot_unavailable', 'snapshots' => unavailable }] if unavailable.any?
+      return [] if initial_snapshot['sha256'] == final_snapshot['sha256']
+
+      [{
+        'severity' => 'invalid',
+        'code' => 'source_changed_during_analysis',
+        'initial_sha256' => initial_snapshot['sha256'],
+        'final_sha256' => final_snapshot['sha256']
+      }]
+    end
+
+    def blocker_health_severity(blocker)
+      return :invalid if blocker.kind == :parse_incomplete && blocker.caller_domain == :runtime
+      return :invalid if INVALID_BLOCKER_KINDS.include?(blocker.kind)
+
+      :degraded if DEGRADED_BLOCKER_KINDS.include?(blocker.kind)
+    end
+
+    def blocker_health_reason(blocker, severity)
+      metadata = blocker.metadata
+      {
+        'severity' => severity.to_s,
+        'code' => blocker.kind.to_s,
+        'message' => blocker.reason,
+        'source' => blocker.source.respond_to?(:to_h) ? blocker.source.to_h : blocker.source.to_s,
+        'file' => metadata['file'] || metadata[:file],
+        'line' => metadata['line'] || metadata[:line]
+      }.compact
+    end
+
+    def verified_source_snapshot(initial_snapshot, final_snapshot)
+      status = if initial_snapshot['status'] != 'complete' || final_snapshot['status'] != 'complete'
+                 'unavailable'
+               elsif initial_snapshot['sha256'] == final_snapshot['sha256']
+                 'match'
+               else
+                 'mismatch'
+               end
+      initial_snapshot.merge(
+        'verification' => {
+          'status' => status,
+          'final_status' => final_snapshot['status'],
+          'final_sha256' => final_snapshot['sha256']
+        }
+      )
+    end
+
+    def measure_phase(profiler, name, &block)
+      return block.call unless profiler
+
+      profiler.measure(name, &block)
+    end
+
+    def report_index_size_bytes(graph)
+      node_bytes = graph.nodes.values.sum { |node| JSON.generate(node.to_h).bytesize }
+      call_site_bytes = graph.call_sites.sum { |site| JSON.generate(site.to_h).bytesize }
+      edge_bytes = graph.edges.sum { |edge| JSON.generate(edge.to_h).bytesize }
+      node_bytes + call_site_bytes + edge_bytes
+    end
+
+    def normalize_rta_pruning(value)
+      mode = value.to_s
+      return mode.to_sym if Configuration::RTA_PRUNING_MODES.include?(mode)
+
+      raise Error, "RTA pruning must be one of: #{Configuration::RTA_PRUNING_MODES.join(', ')}"
+    end
+
+    def analyzer_for_pruning(analyzer, mode)
+      return analyzer unless analyzer.is_a?(Analyzers::Static::RTA)
+
+      configured = analyzer.with_pruning(mode)
+      return configured unless mode == :rank_only
+
+      configured.without_redundant_edges
+    end
+
+    def run_analyzer(graph, project, configured_analyzer, rta_pruning)
+      analyzer = analyzer_for_pruning(configured_analyzer, rta_pruning)
+      profile = analyzer.profile
+      raise TypeError, "#{analyzer.class} returned an invalid analyzer profile" unless profile.is_a?(AnalyzerProfile)
+
+      graph.add_profile(profile)
+      result = analyzer.analyze(graph, project)
+      result = Analyzers::LegacyResultAdapter.new(graph: graph, profile: profile).adapt(result)
+      validate_result_capabilities!(analyzer, result)
+      graph.apply_result(result, refresh: false)
+      [profile, result]
+    rescue StandardError => e
+      graph.add_blocker(analyzer_failure_blocker(analyzer || configured_analyzer, profile, e))
+      [profile, nil]
+    end
+
+    def analyzer_failure_blocker(analyzer, profile, error)
+      analyzer_name = profile&.name&.to_s || analyzer.class.name
+      error_message = safe_error_message(error)
+      Blocker.new(
+        kind: :analyzer_failure,
+        scope_kind: :global,
+        scope_value: '*',
+        source: analyzer_name,
+        reason: "Analyzer #{analyzer_name} failed: #{error.class}: #{error_message}",
+        suggested_action: :fix_analyzer,
+        metadata: {
+          'analyzer' => analyzer_name,
+          'analyzer_class' => analyzer.class.name,
+          'caller_domain' => 'runtime',
+          'error_class' => error.class.name,
+          'error_message' => error_message
+        }
+      )
+    end
+
+    def validate_result_capabilities!(analyzer, result)
+      complete = Array(result.resolutions).any? { |record| record.resolution.status == :complete }
+      return unless complete
+      return if Array(analyzer.capabilities).map(&:to_sym).include?(:complete_resolution)
+
+      raise TypeError, "#{analyzer.class} emitted complete resolution without complete_resolution capability"
+    end
+
+    def unsound_rta_pruning_blocker
+      Blocker.new(
+        kind: :unsound_rta_pruning,
+        scope_kind: :global,
+        scope_value: '*',
+        source: :configuration,
+        reason: 'Legacy RTA pruning can remove reachable targets without complete allocation evidence',
+        suggested_action: :use_rank_only_rta,
+        metadata: { 'caller_domain' => 'runtime', 'rta_pruning' => 'legacy' }
+      )
+    end
+
+    def safe_error_message(error)
+      message = error.message.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+      return message if message.bytesize <= ANALYZER_ERROR_MESSAGE_BYTES
+
+      "#{message.byteslice(0, ANALYZER_ERROR_MESSAGE_BYTES).to_s.scrub}\u2026"
+    rescue StandardError, SystemStackError
+      'unavailable'
+    end
+
     def apply_entry_points(graph, project)
       EntryPoints::Plain.new.apply(graph, project)
       EntryPoints::Rails.new.apply(graph, project)
       EntryPoints::Test.new.apply(graph, project)
-      graph.entrypoint_hints.each { |entry| graph.add_entry_point(entry.node_id, entry.reason) }
+      graph.entrypoint_hints.each do |entry|
+        graph.add_entry_point(
+          entry.node_id,
+          entry.reason,
+          domain: entry.domain,
+          evidence: entry.evidence
+        )
+      end
+      WorldPolicy.new(graph: graph, project: project).apply
     end
 
     def configured_analyzers
@@ -85,8 +302,6 @@ module Necropsy
     end
 
     def custom_analyzer_definition(entry)
-      return [entry, nil] unless entry.is_a?(Hash)
-
       [entry.fetch('class'), entry['require']]
     end
 

data/lib/necropsy/runtime_feedback.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module Necropsy
+  # Compares positive runtime target observations with the static target set.
+  #
+  # Runtime observations may discover a target that the static resolver did not
+  # enumerate.  That is a safety signal and a useful regression fixture, but an
+  # unobserved static target is never removed from the model.
+  class RuntimeFeedback
+    SCHEMA_VERSION = 1
+    DEFAULT_FIXTURE_LIMIT = 32
+
+    def initialize(static_targets:, observed_targets:, max_fixtures: DEFAULT_FIXTURE_LIMIT)
+      @static_targets = normalize_static_targets(static_targets)
+      @observed_targets = normalize_observed_targets(observed_targets)
+      @max_fixtures = Integer(max_fixtures)
+      raise ArgumentError, 'max_fixtures must be non-negative' if @max_fixtures.negative?
+    rescue ArgumentError, TypeError => e
+      raise e unless e.message.start_with?('invalid value for Integer()', 'no implicit conversion of')
+
+      raise ArgumentError, 'max_fixtures must be a non-negative integer'
+    end
+
+    def call
+      observed_by_site = @observed_targets.group_by { |target| target.fetch('call_site_id') }
+      static_by_site = @static_targets
+      missing_static = @observed_targets.filter_map do |target|
+        static = static_by_site.fetch(target.fetch('call_site_id'), [])
+        next if static.include?(target.fetch('target_definition_id'))
+
+        target.merge(
+          'classification' => 'missing_static_target',
+          'safety' => 'safety_bug'
+        )
+      end
+      fixtures = missing_static.first(@max_fixtures).map { |target| fixture_candidate(target) }
+      unobserved_static = static_by_site.flat_map do |call_site_id, targets|
+        observed = observed_by_site.fetch(call_site_id, []).map { |target| target.fetch('target_definition_id') }
+        targets.reject { |target| observed.include?(target) }.map do |target|
+          { 'call_site_id' => call_site_id, 'target_definition_id' => target, 'informational' => true }
+        end
+      end
+
+      {
+        'schema_version' => SCHEMA_VERSION,
+        'policy' => 'positive_only',
+        'comparison' => {
+          'call_sites' => (static_by_site.keys | observed_by_site.keys).length,
+          'static_target_count' => static_by_site.values.sum(&:length),
+          'observed_target_count' => @observed_targets.length
+        },
+        'missing_static_targets' => missing_static,
+        'unexpected_targets' => missing_static,
+        'unobserved_static_targets' => unobserved_static,
+        'fixture_candidates' => fixtures,
+        'fixture_exported' => false
+      }
+    end
+
+    def write_fixture_candidates(path)
+      payload = call
+      candidates = payload.fetch('fixture_candidates')
+      destination = File.expand_path(path)
+      FileUtils.mkdir_p(File.dirname(destination))
+      temporary = "#{destination}.tmp-#{Process.pid}-#{Thread.current.object_id}"
+      File.write(temporary, "#{JSON.pretty_generate(candidates)}\n")
+      File.rename(temporary, destination)
+      payload.merge('fixture_exported' => true, 'fixture_path' => destination)
+    rescue SystemCallError => e
+      raise Error, "Could not export runtime feedback fixtures: #{e.message}"
+    ensure
+      FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
+    end
+
+    def self.from_graph(graph, observed_targets:, max_fixtures: DEFAULT_FIXTURE_LIMIT)
+      static_targets = graph.resolution_records.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |record, result|
+        result[record.resolution.call_site_id].concat(record.resolution.target_definition_ids)
+      end
+      new(static_targets: static_targets, observed_targets: observed_targets, max_fixtures: max_fixtures)
+    end
+
+    private
+
+    def normalize_static_targets(value)
+      raise ArgumentError, 'static_targets must be a Hash' unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(call_site_id, targets), result|
+        site = identifier(call_site_id, 'call_site_id')
+        result[site] = Array(targets).map { |target| identifier(target, 'target_definition_id') }.uniq.sort
+      end.sort.to_h.freeze
+    end
+
+    def normalize_observed_targets(value)
+      Array(value).map do |target|
+        raise ArgumentError, 'observed target must be a Hash' unless target.is_a?(Hash)
+
+        data = target.to_h { |key, item| [key.to_s, item] }
+        call_site_id = identifier(data['call_site_id'], 'call_site_id')
+        target_definition_id = identifier(
+          data['target_definition_id'] || data['target_id'], 'target_definition_id'
+        )
+        normalized = {
+          'call_site_id' => call_site_id,
+          'target_definition_id' => target_definition_id
+        }
+        %w[receiver_class file line].each do |key|
+          normalized[key] = data[key] unless data[key].nil?
+        end
+        normalized
+      end.uniq.sort_by { |target| [target['call_site_id'], target['target_definition_id']] }.freeze
+    end
+
+    def fixture_candidate(target)
+      {
+        'call_site_id' => target.fetch('call_site_id'),
+        'target_definition_id' => target.fetch('target_definition_id'),
+        'receiver_class' => target['receiver_class'],
+        'source' => {
+          'file' => target['file'],
+          'line' => target['line']
+        }.compact,
+        'reason' => 'runtime target was not present in the static target set'
+      }.compact
+    end
+
+    def identifier(value, field)
+      normalized = value.to_s
+      raise ArgumentError, "#{field} must not be empty" if normalized.empty?
+
+      normalized
+    end
+  end
+end

data/lib/necropsy/semantics_matrix.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'prism'
+require 'yaml'
+
+module Necropsy
+  class SemanticsMatrix
+    SCHEMA_VERSION = 'necropsy.semantics.v1'
+    STATUSES = %w[exact partial blocked unsupported].freeze
+
+    EXACT_PRISM_NODES = %i[
+      AliasMethodNode ArgumentsNode ArrayNode AssocNode BeginNode BlockArgumentNode BlockLocalVariableNode
+      BlockParameterNode BlockParametersNode ClassNode ConstantPathNode ConstantReadNode ConstantTargetNode
+      DefNode FalseNode FloatNode ForwardingArgumentsNode ForwardingParameterNode HashNode ImaginaryNode
+      ImplicitNode ImplicitRestNode IntegerNode ItLocalVariableReadNode ItParametersNode KeywordHashNode
+      KeywordRestParameterNode LocalVariableReadNode LocalVariableTargetNode ModuleNode NilNode
+      NoKeywordsParameterNode NumberedParametersNode NumberedReferenceReadNode OptionalKeywordParameterNode
+      OptionalParameterNode ParametersNode ParenthesesNode RationalNode RegularExpressionNode
+      RequiredKeywordParameterNode RequiredParameterNode RestParameterNode SelfNode SourceEncodingNode
+      SourceFileNode SourceLineNode StatementsNode StringNode SymbolNode TrueNode
+    ].to_set.freeze
+
+    PARTIAL_PRISM_NODES = %i[
+      AliasGlobalVariableNode AlternationPatternNode AndNode ArrayPatternNode AssocSplatNode
+      BackReferenceReadNode BlockNode BreakNode CallAndWriteNode CallNode CallOperatorWriteNode CallOrWriteNode
+      CallTargetNode CapturePatternNode CaseMatchNode CaseNode ClassVariableAndWriteNode
+      ClassVariableOperatorWriteNode ClassVariableOrWriteNode ClassVariableReadNode ClassVariableTargetNode
+      ClassVariableWriteNode ConstantAndWriteNode ConstantOperatorWriteNode ConstantOrWriteNode
+      ConstantPathAndWriteNode ConstantPathOperatorWriteNode ConstantPathOrWriteNode ConstantPathTargetNode
+      ConstantPathWriteNode ConstantWriteNode DefinedNode ElseNode EmbeddedStatementsNode EmbeddedVariableNode
+      EnsureNode FindPatternNode FlipFlopNode ForNode ForwardingSuperNode GlobalVariableAndWriteNode
+      GlobalVariableOperatorWriteNode GlobalVariableOrWriteNode GlobalVariableReadNode GlobalVariableTargetNode
+      GlobalVariableWriteNode HashPatternNode IfNode InNode IndexAndWriteNode IndexOperatorWriteNode IndexOrWriteNode
+      IndexTargetNode InstanceVariableAndWriteNode InstanceVariableOperatorWriteNode InstanceVariableOrWriteNode
+      InstanceVariableReadNode InstanceVariableTargetNode InstanceVariableWriteNode InterpolatedMatchLastLineNode
+      InterpolatedRegularExpressionNode InterpolatedStringNode InterpolatedSymbolNode InterpolatedXStringNode
+      LambdaNode LocalVariableAndWriteNode LocalVariableOperatorWriteNode LocalVariableOrWriteNode
+      LocalVariableWriteNode MatchLastLineNode MatchPredicateNode MatchRequiredNode MatchWriteNode MultiTargetNode
+      MultiWriteNode NextNode OrNode PinnedExpressionNode PinnedVariableNode PostExecutionNode PreExecutionNode
+      ProgramNode RangeNode RedoNode RescueModifierNode RescueNode RetryNode ReturnNode ShareableConstantNode
+      SingletonClassNode SplatNode SuperNode UndefNode UnlessNode UntilNode WhenNode WhileNode XStringNode YieldNode
+    ].to_set.freeze
+
+    BLOCKED_PRISM_NODES = %i[MissingNode].to_set.freeze
+
+    RUBY_HOOK_STATUS = {
+      'inherited' => 'partial',
+      'included' => 'partial',
+      'extended' => 'partial',
+      'prepended' => 'partial',
+      'method_added' => 'partial',
+      'singleton_method_added' => 'partial',
+      'const_missing' => 'partial',
+      'method_missing' => 'partial',
+      'respond_to_missing?' => 'partial'
+    }.freeze
+
+    def to_h
+      {
+        'schema_version' => SCHEMA_VERSION,
+        'runtime' => { 'ruby' => RUBY_VERSION, 'prism' => Prism::VERSION },
+        'statuses' => STATUSES,
+        'prism_nodes' => prism_nodes,
+        'ruby_hooks' => ruby_hooks,
+        'rails_dsl' => rails_dsl
+      }
+    end
+
+    def render(format: :human)
+      case format.to_sym
+      when :json then JSON.pretty_generate(to_h)
+      when :yaml then YAML.dump(to_h)
+      when :human then render_human
+      else raise Error, "semantics supports human, json, or yaml output (got #{format})"
+      end
+    end
+
+    private
+
+    def prism_nodes
+      prism_node_classes.map do |name|
+        status = prism_status(name)
+        { 'name' => name.to_s, 'status' => status, 'reason' => prism_reason(status) }
+      end
+    end
+
+    def prism_node_classes
+      Prism.constants.filter_map do |name|
+        value = Prism.const_get(name)
+        name if value.is_a?(Class) && value < Prism::Node
+      end.sort_by(&:to_s)
+    end
+
+    def prism_status(name)
+      return 'exact' if EXACT_PRISM_NODES.include?(name)
+      return 'partial' if PARTIAL_PRISM_NODES.include?(name)
+      return 'blocked' if BLOCKED_PRISM_NODES.include?(name)
+
+      'unsupported'
+    end
+
+    def prism_reason(status)
+      case status
+      when 'exact' then 'scanner preserves the node structure without narrowing dispatch unsafely'
+      when 'partial' then 'calls are traversed conservatively but full Ruby runtime semantics are not claimed'
+      when 'blocked' then 'analysis health or a semantic blocker prevents an actionable conclusion'
+      else 'no reviewed scanner semantics are registered for this Prism node version'
+      end
+    end
+
+    def ruby_hooks
+      Confidence::Scorer::RUBY_HOOKS.sort.map do |name|
+        {
+          'name' => name,
+          'status' => RUBY_HOOK_STATUS.fetch(name, 'unsupported'),
+          'reason' => 'recognized as an implicit VM callback; confidence is lowered without claiming a runtime root'
+        }
+      end
+    end
+
+    def rails_dsl
+      entries = {}
+      AstScanner::RAILS_CALLBACK_MACROS.each { |name| entries[name.to_s] = dsl_entry(name, 'callback') }
+      AstScanner::RAILS_GENERATED_METHOD_MACROS.each do |name|
+        entries[name.to_s] = dsl_entry(name, 'generated_method')
+      end
+      EntryPoints::Rails::ROUTE_DSL_CALLS.each { |name| entries[name.to_s] = dsl_entry(name, 'route') }
+      entries.keys.sort.map { |name| entries.fetch(name) }
+    end
+
+    def dsl_entry(name, family)
+      reasons = {
+        'callback' => 'literal callback methods and conditions are rooted; dynamic registration is blocked',
+        'generated_method' => 'literal APIs are grouped by macro source; version-dependent surfaces remain conservative',
+        'route' => 'Prism verifies route DSL calls and literal targets; dynamic targets create scoped blockers'
+      }
+      { 'name' => name.to_s, 'family' => family, 'status' => 'partial', 'reason' => reasons.fetch(family) }
+    end
+
+    def render_human
+      data = to_h
+      counts = data.fetch('prism_nodes').tally { |entry| entry.fetch('status') }
+      [
+        "Semantics matrix #{SCHEMA_VERSION}",
+        "Ruby #{RUBY_VERSION}; Prism #{Prism::VERSION}",
+        "Prism nodes: #{STATUSES.map { |status| "#{status}=#{counts.fetch(status, 0)}" }.join(', ')}",
+        "Ruby hooks: #{data.fetch('ruby_hooks').length}",
+        "Rails DSL entries: #{data.fetch('rails_dsl').length}"
+      ].join("\n")
+    end
+  end
+end

data/lib/necropsy/type_facts.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Necropsy
+  TYPE_FACT_TRUST_LEVELS = %i[authoritative hint conflicting].freeze
+
+  TypeFact = Data.define(:subject, :types, :trust, :source, :complete) do
+    def initialize(subject:, types:, source:, trust: :hint, complete: false)
+      subject = subject.to_s
+      raise ArgumentError, 'type fact subject must not be empty' if subject.empty?
+
+      types = Array(types).map(&:to_s).reject(&:empty?).uniq.sort.freeze
+      raise ArgumentError, 'type fact requires at least one type' if types.empty?
+
+      trust = trust.to_sym
+      raise ArgumentError, "invalid type fact trust: #{trust.inspect}" unless TYPE_FACT_TRUST_LEVELS.include?(trust)
+
+      source = source.to_s
+      raise ArgumentError, 'type fact source must not be empty' if source.empty?
+
+      super(subject: subject.freeze, types: types, trust: trust, source: source.freeze, complete: complete == true)
+    end
+
+    def safe_for_resolution?
+      trust == :authoritative && complete
+    end
+
+    def to_h
+      {
+        'subject' => subject,
+        'types' => types,
+        'trust' => trust.to_s,
+        'source' => source,
+        'complete' => complete
+      }
+    end
+  end
+
+  module TypeProvider
+    module_function
+
+    def profile
+      AnalyzerProfile.new(
+        name: 'none', kind: :type, soundness: :hint,
+        description: 'No external type provider is enabled; core analysis remains independent.', version: '1',
+        assumptions: ['type facts are optional', 'hints never refute a target']
+      )
+    end
+
+    def facts(_project)
+      []
+    end
+  end
+end

data/lib/necropsy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Necropsy
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end