catenary 0.1.0

data/lib/catenary/snapshot/schema.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module Catenary
+  module Snapshot
+    module Schema
+      TOP_LEVEL_KEYS = %w[manifest routes models classes templates mutations static_crosscheck inventory].freeze
+
+      module_function
+
+      # Canonicalize: sort object keys recursively, sort arrays by natural key where determinable.
+      def canonicalize(obj)
+        case obj
+        when Hash
+          obj.keys.sort.each_with_object({}) { |k, h| h[k.to_s] = canonicalize(obj[k]) }
+        when Array
+          arr = obj.map { |e| canonicalize(e) }
+          # Only record collections have a natural key; tuples (source_location, parameters) and
+          # ordered lists (ancestors) must retain their semantic order.
+          arr.all? { |e| e.is_a?(Hash) } && arr.size > 1 ? arr.sort_by { |e| natural_key(e) } : arr
+        else
+          normalize_scalar(obj)
+        end
+      end
+
+      def natural_key(e)
+        return e.to_s unless e.is_a?(Hash)
+
+        [e["name"] || e["path"] || "", e["verb"] || "", e["controller"] || "", e["action"] || "",
+         e["kind"] || "", e["table_name"] || "", e["id"] || "", JSON.generate(e)]
+      end
+
+      def normalize_scalar(v)
+        v.is_a?(Symbol) ? v.to_s : v
+      end
+
+      def canonical_json(doc)
+        JSON.generate(canonicalize(doc))
+      end
+
+      def snapshot_id(doc)
+        Digest::SHA256.hexdigest(canonical_json(doc))
+      end
+
+      def validate!(doc)
+        missing = TOP_LEVEL_KEYS - doc.keys.map(&:to_s)
+        raise Error.new("invalid_snapshot", "Snapshot missing keys: #{missing.join(', ')}", { "missing" => missing }) unless missing.empty?
+        raise Error.new("invalid_snapshot", "Schema version mismatch") unless doc.dig("manifest", "schema_version") == SNAPSHOT_SCHEMA_VERSION
+
+        true
+      end
+
+      def empty_document(manifest:, routes: [], models: [], classes: [], templates: [], mutations: [], static_crosscheck: {}, inventory: [])
+        {
+          "manifest" => manifest.merge("schema_version" => SNAPSHOT_SCHEMA_VERSION),
+          "routes" => routes, "models" => models, "classes" => classes,
+          "templates" => templates, "mutations" => mutations,
+          "static_crosscheck" => static_crosscheck, "inventory" => inventory
+        }
+      end
+    end
+  end
+end

data/lib/catenary/staging/boot_runner.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "tmpdir"
+require_relative "../snapshot/schema"
+
+module Catenary
+  module Staging
+    class BootRunner
+      BOOTSTRAP = File.expand_path("bootstrap.rb", __dir__)
+
+      def initialize(config)
+        @config = config
+      end
+
+      # Runs bootstrap twice in fresh subprocesses; canonical-diff is the nondeterminism gate.
+      def run_snapshot
+        first = run_once
+        second = run_once
+        c1 = Snapshot::Schema.canonical_json(first)
+        c2 = Snapshot::Schema.canonical_json(second)
+        if c1 != c2
+          diff = diff_summary(first, second)
+          raise Error.new("nondeterministic_snapshot", "Double-boot snapshots differ: #{diff.join('; ')}", { "diff" => diff })
+        end
+        first
+      end
+
+      def run_once
+        Dir.mktmpdir("catenary-stage") do |dir|
+          out = File.join(dir, "snapshot.json")
+          env = scrubbed_env
+          cmd = staging_command(out)
+          stdout, stderr, status = Open3.capture3(env, *cmd, chdir: @config.app_path)
+          unless status.success?
+            parsed = parse_error(stderr) || parse_error(stdout)
+            raise(parsed || Error.new("staging_boot_failed", "Staging boot failed (exit #{status.exitstatus}): #{stderr.lines.first(5).join}", { "stderr" => stderr, "stdout" => stdout }))
+          end
+          raise Error.new("staging_boot_failed", "Bootstrap produced no snapshot") unless File.exist?(out)
+
+          doc = JSON.parse(File.read(out))
+          doc["manifest"]["env_allowlist"] = @config.env_allowlist.sort
+          doc["mutations"] = Array(doc["mutations"]).map { |m| m.transform_values { |v| v.is_a?(String) ? v.gsub(/0x[0-9a-f]{6,}/i, "0xADDR") : v } }.uniq { |m| JSON.generate(m) }.sort_by { |m| JSON.generate(m) }
+          doc
+        end
+      end
+
+      private
+
+      def staging_command(out)
+        args = [BOOTSTRAP, File.expand_path(@config.app_path), out]
+        if File.exist?(File.join(@config.app_path, "Gemfile"))
+          ["bundle", "exec", RbConfig.ruby, *args]
+        else
+          [RbConfig.ruby, *args]
+        end
+      end
+
+      def scrubbed_env
+        env = {}
+        # Scrub inherited env: only allowlist + required staging keys + minimal process essentials.
+        (@config.env_allowlist).each { |k| env[k] = ENV[k] if ENV.key?(k) }
+        @config.secrets.each { |k, v| env[k.to_s] = v.to_s }
+        env["RAILS_ENV"] = @config.rails_env
+        env["CATENARY_STAGING"] = "1"
+        env["PATH"] = [File.dirname(RbConfig.ruby), ENV["PATH"]].compact.join(":")
+        env["HOME"] = ENV["HOME"]
+        env["LANG"] = ENV["LANG"] || "C.UTF-8"
+        # Explicitly unset common secret-bearing vars not allowlisted
+        %w[DATABASE_URL SECRET_KEY_BASE AWS_SECRET_ACCESS_KEY GITHUB_TOKEN].each do |k|
+          env[k] = nil unless @config.env_allowlist.include?(k) || @config.secrets.key?(k)
+        end
+        ENV.each_key { |k| env[k] = nil if k.match?(/\A(BUNDLE_|BUNDLER_|GEM_|RUBYGEMS_)/) }
+        %w[BUNDLE_GEMFILE BUNDLE_PATH RUBYOPT RUBYLIB BUNDLER_VERSION GEM_HOME GEM_PATH RUBYGEMS_GEMDEPS BUNDLE_BIN_PATH BUNDLE_LOCKFILE].each { |k| env[k] = nil }
+        env
+      end
+
+      def parse_error(text)
+        text.each_line do |line|
+          j = JSON.parse(line) rescue next
+          next unless j["error"]
+
+          return Error.new(j["error"]["code"] || "staging_boot_failed", j["error"]["message"] || line, j["error"]["details"] || {})
+        end
+        nil
+      end
+
+      def diff_summary(a, b)
+        diffs = []
+        %w[routes models classes templates mutations].each do |k|
+          diffs << "#{k} differ" if Snapshot::Schema.canonical_json(a[k]) != Snapshot::Schema.canonical_json(b[k])
+        end
+        diffs << "manifest differs" if Snapshot::Schema.canonical_json(a["manifest"].except("git_sha")) != Snapshot::Schema.canonical_json(b["manifest"].except("git_sha"))
+        diffs = ["snapshot differs"] if diffs.empty?
+        diffs
+      end
+    end
+  end
+end

data/lib/catenary/staging/bootstrap.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+# Runs INSIDE the target app subprocess. Must use only Rails 8.1+ / Ruby 4.0+ APIs.
+# Args: app_path snapshot_out_path
+require "json"
+require "digest"
+
+app_path = File.expand_path(ARGV[0])
+out_path = ARGV[1]
+mutations = []
+$catenary_mutations = mutations
+
+def rel(path, root)
+  return nil if path.nil?
+
+  p = File.expand_path(path)
+  p.start_with?(root) ? p.sub("#{root}/", "") : p
+rescue StandardError
+  path
+end
+
+def safe_json(v, depth = 0)
+  return nil if depth > 3
+
+  case v
+  when String, Integer, Float, true, false, nil then v
+  when Symbol then v.to_s
+  when Array then v.map { |e| safe_json(e, depth + 1) }
+  when Hash then v.each_with_object({}) { |(k, val), h| h[k.to_s] = safe_json(val, depth + 1) }
+  when Class, Module then v.name
+  when Proc, Method
+    loc = v.source_location rescue nil
+    loc ? "proc:#{loc[0]}:#{loc[1]}" : v.class.to_s
+  else
+    s = v.to_s
+    s.match?(/0x[0-9a-f]{6,}/i) ? v.class.to_s : s
+  end
+rescue StandardError
+  v.class.to_s
+end
+
+begin
+  # Platform floor inside subprocess
+  unless Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("4.0")
+    warn JSON.generate({ "error" => { "code" => "unsupported_platform", "message" => "Ruby #{RUBY_VERSION} < 4.0" } })
+    exit 3
+  end
+  ENV["RAILS_ENV"] ||= "production"
+  require File.join(app_path, "config/environment")
+
+  rails_v = defined?(Rails) && Rails.respond_to?(:version) ? Rails.version : nil
+  rails_v ||= defined?(Rails::VERSION) ? Rails::VERSION::STRING : nil
+  ok_rails = false
+  if rails_v
+    seg = Gem::Version.new(rails_v).segments
+    ok_rails = seg[0] == 8 && seg[1] >= 1
+  end
+  unless ok_rails
+    warn JSON.generate({ "error" => { "code" => "unsupported_platform", "message" => "Rails #{rails_v} < 8.1 or not 8.x", "details" => { "ruby" => RUBY_VERSION, "rails" => rails_v } } })
+    exit 3
+  end
+  unless Rails::VERSION::MAJOR == 8 && Rails::VERSION::MINOR >= 1
+    warn JSON.generate({ "error" => { "code" => "unsupported_platform", "message" => "Rails version accessor mismatch" } })
+    exit 3
+  end
+
+  Rails.application.eager_load!
+
+  # Require Zeitwerk-unloaded files under eager load paths
+  unloadable = []
+  begin
+    paths = Rails.application.config.eager_load_paths.flat_map { |p| Dir[File.join(p, "**/*.rb")] }
+    paths.each do |f|
+      next if $LOADED_FEATURES.include?(File.expand_path(f))
+
+      begin
+        require File.expand_path(f)
+      rescue Exception => e # rubocop:disable Lint/RescueExceptions
+        unloadable << { "type" => "unloadable_file", "name" => rel(f, app_path), "error" => "#{e.class}: #{e.message}", "retain_forever" => true }
+      end
+    end
+  rescue Exception => e # rubocop:disable Lint/RescueExceptions
+    unloadable << { "type" => "unloadable_scan_error", "name" => e.class.to_s, "error" => e.message }
+  end
+  mutations.concat(unloadable)
+
+  # DB introspection (requires reachable migrated DB for AR apps)
+  if defined?(ActiveRecord::Base)
+    begin
+      ActiveRecord::Base.connection_pool.with_connection { |c| c.tables }
+    rescue Exception => e # rubocop:disable Lint/RescueExceptions
+      warn JSON.generate({ "error" => { "code" => "staging_db_unreachable", "message" => "#{e.class}: #{e.message}" } })
+      exit 4
+    end
+  end
+
+  # Mutation traps AFTER eager load (record only)
+  trap_mod = Module.new do
+    define_method(:method_added) do |name|
+      $catenary_mutations << { "type" => "method_added", "name" => "#{self}##{name}", "post_eager_load" => true }
+      super(name) if defined?(super)
+    rescue StandardError
+      nil
+    end
+    define_method(:singleton_method_added) do |name|
+      $catenary_mutations << { "type" => "singleton_method_added", "name" => "#{self}.#{name}", "post_eager_load" => true }
+    rescue StandardError
+      nil
+    end
+    define_method(:append_features) do |mod|
+      $catenary_mutations << { "type" => "append_features", "name" => "#{self} appended to #{mod}", "post_eager_load" => true }
+      super(mod)
+    end
+    define_method(:const_missing) do |name|
+      $catenary_mutations << { "type" => "const_missing", "name" => "#{self}::#{name}", "post_eager_load" => true }
+      super(name)
+    end
+  end
+  Module.prepend(trap_mod)
+
+  # Routes
+  routes = []
+  Rails.application.routes.routes.each do |r|
+    defaults = r.defaults || {}
+    verb = r.verb.is_a?(Regexp) ? r.verb.source.gsub(/\\A|\\z|\(|\)|\^|\$/, "") : r.verb.to_s
+    verb = verb.empty? ? "GET" : verb
+    routes << {
+      "verb" => verb, "path" => r.path.spec.to_s, "controller" => defaults[:controller]&.to_s,
+      "action" => defaults[:action]&.to_s, "name" => r.name&.to_s,
+      "constraints" => safe_json(r.constraints || {})
+    }
+  end
+  helper_names = []
+  begin
+    helper_names = Rails.application.routes.url_helpers.instance_methods.map(&:to_s).sort
+  rescue StandardError
+    helper_names = []
+  end
+
+  # Models
+  models = []
+  model_classes = []
+  if defined?(ActiveRecord::Base)
+    model_classes = ActiveRecord::Base.descendants.sort_by(&:name)
+    model_classes.each do |m|
+      next unless m.name
+
+      cols = {}
+      begin
+        m.columns_hash.each { |k, c| cols[k] = { "sql_type" => c.sql_type, "type" => c.type.to_s, "null" => c.null, "default" => safe_json(c.default) } }
+      rescue StandardError
+        cols = {}
+      end
+      refls = []
+      begin
+        m.reflections.each do |k, ref|
+          refls << { "name" => k.to_s, "macro" => ref.macro.to_s, "klass_name" => (ref.klass.name rescue nil), "foreign_key" => ref.foreign_key.to_s, "options" => safe_json(ref.options || {}) }
+        end
+      rescue StandardError
+        nil
+      end
+      vals = []
+      begin
+        (m._validators || {}).each do |attr, vs|
+          Array(vs).each { |v| vals << { "attributes" => Array(attr).map(&:to_s), "kind" => v.kind.to_s, "options" => safe_json(v.options || {}) } }
+        end
+      rescue StandardError
+        nil
+      end
+      cbs = {}
+      begin
+        m.methods.grep(/\A_(.+)_callbacks\z/).each do |mm|
+          kind = mm.to_s.sub(/\A_/, "").sub(/_callbacks\z/, "")
+          chain = m.public_send(mm) rescue next
+          filters = Array(chain).map { |cb| f = (cb.filter rescue cb); f.is_a?(Proc) ? "proc:#{Array(f.source_location).join(':')}" : f.to_s.gsub(/0x[0-9a-f]{6,}/i, f.class.to_s) }
+          cbs[kind] = filters
+        end
+      rescue StandardError
+        nil
+      end
+      top_loc = (Object.const_source_location(m.name.split("::").first) rescue nil)
+      model_app_defined = !!(top_loc && top_loc[0].to_s.start_with?(app_path))
+      models << { "name" => m.name, "app_defined" => model_app_defined, "table_name" => (m.table_name rescue nil), "columns" => cols, "reflections" => refls.sort_by { |x| x["name"] }, "validators" => vals, "callbacks" => cbs }
+    end
+  end
+
+  # Classes reachable from routes/models/jobs/mailers/channels
+  seed = []
+  routes.each do |r|
+    next unless r["controller"]
+
+    const_name = "#{r['controller'].split('/').map { |s| s.split('_').map(&:capitalize).join }.join('::')}Controller"
+    begin
+      seed << Object.const_get(const_name)
+    rescue StandardError
+      nil
+    end
+  end
+  seed.concat(model_classes)
+  %w[ActiveJob::Base ActionMailer::Base ActionCable::Channel::Base].each do |n|
+    begin
+      base = Object.const_get(n)
+      seed.concat(base.descendants)
+    rescue StandardError
+      nil
+    end
+  end
+  # Zeitwerk-managed constants under app/ (helpers etc. reachable via controllers)
+  begin
+    Rails.autoloaders.each do |loader|
+      Dir[File.join(app_path, "app/**/*.rb")].each do |f|
+        cpath = loader.cpath_expected_at(f) rescue nil
+        next unless cpath
+        begin
+          seed << Object.const_get(cpath)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  rescue StandardError
+    nil
+  end
+  # Secondary constants in multi-constant files (e.g. error classes above a controller)
+  begin
+    ObjectSpace.each_object(Module) do |m|
+      begin
+        next unless m.name
+        top = m.name.split("::").first
+        loc = Object.const_source_location(top) rescue nil
+        seed << m if loc && loc[0].to_s.start_with?(app_path)
+      rescue StandardError
+        next
+      end
+    end
+  rescue StandardError
+    nil
+  end
+  classes_by_name = {}
+  queue = seed.compact.select { |k| k.is_a?(Module) && k.name }
+  visited = {}
+  until queue.empty?
+    klass = queue.shift
+    next if visited[klass.name]
+
+    visited[klass.name] = true
+    begin
+      klass.ancestors.each { |a| queue << a if a.is_a?(Module) && a.name && a.name !~ /\A(Active|Action|Rails|Zeitwerk)/ }
+    rescue StandardError
+      nil
+    end
+    methods = []
+    begin
+      (klass.instance_methods + klass.private_instance_methods + klass.protected_instance_methods).uniq.each do |mn|
+        um = klass.instance_method(mn) rescue next
+        next unless um.owner == klass
+        loc = um.source_location
+        methods << { "name" => mn.to_s, "owner" => (um.owner.name rescue nil), "visibility" => (klass.private_instance_methods.include?(mn) ? "private" : klass.protected_instance_methods.include?(mn) ? "protected" : "public"), "parameters" => um.parameters.map { |t, n| [t.to_s, n&.to_s] }, "source_location" => loc ? [rel(loc[0], app_path), loc[1]] : nil, "app_defined" => !!(loc && !rel(loc[0], app_path).to_s.start_with?("/", "<")), "singleton" => false }
+      end
+      (klass.singleton_methods + klass.private_methods).uniq.each do |mn|
+        um = klass.method(mn) rescue next
+        next unless um.owner == klass.singleton_class || um.owner == klass
+        loc = um.source_location rescue nil
+        methods << { "name" => mn.to_s, "owner" => (um.owner.name rescue nil), "visibility" => "public", "parameters" => (um.parameters.map { |t, n| [t.to_s, n&.to_s] } rescue []), "source_location" => loc ? [rel(loc[0], app_path), loc[1]] : nil, "app_defined" => !!(loc && !rel(loc[0], app_path).to_s.start_with?("/", "<")), "singleton" => true }
+      end
+    rescue StandardError
+      nil
+    end
+    app_defined = seed.include?(klass) || methods.any? { |m| m["source_location"] && !m["source_location"][0].to_s.start_with?("/", "<") }
+    if app_defined
+      classes_by_name[klass.name] = {
+        "name" => klass.name, "app_defined" => app_defined, "superclass" => (klass.is_a?(Class) ? klass.superclass&.name : nil),
+        "ancestors" => (klass.ancestors.map(&:name).compact rescue []),
+        "methods" => methods.sort_by { |x| [x["name"], x["singleton"].to_s] }
+      }
+    end
+  end
+
+  templates = []
+  begin
+    view_paths = Array(Rails.application.config.paths["app/views"].existent)
+  rescue StandardError
+    view_paths = [File.join(app_path, "app/views")]
+  end
+  view_paths.each do |vp|
+    Dir[File.join(vp, "**/*")].each do |f|
+      next if File.directory?(f)
+
+      base = File.basename(f)
+      handler = base.include?(".erb") || base.end_with?(".erb") ? "erb" : (base.split(".").last || "")
+      format = base.split(".")[1] || "html"
+      templates << { "path" => rel(f, app_path), "format" => format, "handler" => handler }
+    end
+  end
+
+  manifest = {
+    "app_path" => app_path, "schema_version" => 2,
+    "git_sha" => (system("git -C #{app_path} rev-parse HEAD >/dev/null 2>&1") ? `git -C #{app_path} rev-parse HEAD`.strip : nil),
+    "gemfile_lock_sha256" => (File.exist?(File.join(app_path, "Gemfile.lock")) ? Digest::SHA256.file(File.join(app_path, "Gemfile.lock")).hexdigest : nil),
+    "ruby_version" => RUBY_VERSION, "rails_version" => rails_v, "rails_env" => ENV["RAILS_ENV"],
+    "env_allowlist" => ENV.keys.grep(/\ACATENARY_/).sort, "route_helper_names" => helper_names
+  }
+  # env_allowlist names are filled by parent from config (sorted names only, never secret values); placeholder replaced there.
+  doc = {
+    "manifest" => manifest, "routes" => routes, "models" => models,
+    "classes" => classes_by_name.values.sort_by { |c| c["name"] },
+    "templates" => templates.sort_by { |t| t["path"] },
+    "mutations" => mutations, "static_crosscheck" => {}, "inventory" => []
+  }
+  File.write(out_path, JSON.generate(doc))
+rescue SystemExit
+  raise
+rescue Exception => e # rubocop:disable Lint/RescueExceptions
+  warn JSON.generate({ "error" => { "code" => "staging_boot_failed", "message" => "#{e.class}: #{e.message}", "details" => { "backtrace" => Array(e.backtrace).first(20) } } })
+  exit 5
+end

data/lib/catenary/static/rubydex_graph.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require_relative "../snapshot/schema"
+
+module Catenary
+  module Static
+    # Only file allowed to require rubydex.
+    class RubydexGraph
+      attr_reader :declarations, :crosscheck
+
+      def initialize(app_path)
+        @app_path = File.expand_path(app_path)
+      end
+
+      def build
+        begin
+          require "rubydex"
+        rescue LoadError => e
+          raise Error.new("rubydex_unavailable", "rubydex gem required: #{e.message}")
+        end
+        files = Dir[File.join(@app_path, "**/*.{rb,rake,rbs,ru}")].reject { |f| f.include?("/vendor/") || f.include?("/node_modules/") || f.include?("/.git/") }
+        graph = Rubydex::Graph.new
+        begin
+          graph.index_all(files)
+          graph.resolve
+        rescue StandardError => e
+          raise Error.new("rubydex_index_failed", "Rubydex failed to index #{@app_path}: #{e.class}: #{e.message}")
+        end
+        @graph = graph
+        decls = extract_declarations(graph, files)
+        const_refs = extract_constant_references(graph)
+        @declarations = decls
+        @crosscheck = {
+          "declarations" => decls,
+          "constant_references" => const_refs,
+          "entries" => [], # filled by cross_check against snapshot
+          "files" => files.map { |f| relative(f) }.sort
+        }
+        @crosscheck
+      end
+
+      # Cross-check rules (a)-(d). Runtime wins; disagreement demotes only.
+      def cross_check(snapshot, lazy_files: [])
+        build unless @crosscheck
+        entries = []
+        snapshot_classes = {}
+        Array(snapshot["classes"]).each { |c| snapshot_classes[c["name"]] = c }
+        decl_by_name = {}
+        @declarations.each { |d| decl_by_name[d["name"]] = d }
+
+        # (a) static_only
+        @declarations.each do |d|
+          next unless %w[class module].include?(d["kind"])
+          next unless d["name"].match?(/\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/)
+          next if snapshot_classes.key?(d["name"])
+          next unless d["definitions"].any? { |df| df["file"].to_s.start_with?("app/") }
+
+          entries << { "type" => "static_only", "name" => d["name"], "file" => d["definitions"].first["file"], "reason" => "not_loaded_at_boot" }
+        end
+        # (b) runtime_only
+        snapshot_classes.each_key do |name|
+          entries << { "type" => "runtime_only", "name" => name, "reason" => "dynamic_or_unindexed" } unless decl_by_name.key?(name)
+        end
+        # (d) ancestor mismatch for app-defined classes: compare only ancestors declared in app files in both sources
+        app_defined = @declarations.select { |d| d["definitions"].any? { |df| df["file"].to_s.start_with?("app/", "lib/", "config/") } }.map { |d| d["name"] }
+        snapshot_classes.each do |name, klass|
+          next unless app_defined.include?(name)
+          decl = decl_by_name[name]
+          next unless decl && decl["ancestors"] && !decl["ancestors"].empty?
+          # Compare order of app-defined ancestors present in BOTH linearizations; framework modules
+          # Rubydex cannot resolve (runtime-only includes) are excluded, per runtime-wins precedence.
+          common = (klass["ancestors"] & decl["ancestors"] & app_defined)
+          app_anc_snap = klass["ancestors"].select { |a| common.include?(a) }
+          app_anc_dex = decl["ancestors"].select { |a| common.include?(a) }
+          entries << { "type" => "ancestor_mismatch", "name" => name, "reason" => "ancestor_mismatch", "snapshot" => app_anc_snap, "rubydex" => app_anc_dex } if app_anc_snap != app_anc_dex
+        end
+        # (c) is evaluated per substitution in lowering/validation via resolve_constant_name
+        result = @crosscheck.merge("entries" => entries.sort_by { |e| [e["type"], e["name"]] })
+        result["hash"] = Digest::SHA256.hexdigest(Snapshot::Schema.canonical_json(result.reject { |k, _| k == "hash" }))
+        result
+      end
+
+      # Rubydex lexical resolution: returns fully-qualified declaration name or nil.
+      def resolve_constant_name(name, nesting = [])
+        return nil unless @graph
+
+        decl = @graph.resolve_constant(name.to_s, Array(nesting).map(&:to_s)) rescue nil
+        decl&.name
+      end
+
+      def definitions_for(name)
+        d = @declarations&.find { |x| x["name"] == name }
+        d ? d["definitions"] : []
+      end
+
+      # Build a graph over another tree (used by Doctor Yellow for generated tree)
+      def self.build_for(path)
+        g = new(path)
+        g.build
+        g
+      end
+
+      private
+
+      def relative(path)
+        p = File.expand_path(path)
+        p.start_with?(@app_path) ? p.sub("#{@app_path}/", "") : p
+      end
+
+      def loc_string(loc)
+        uri = loc.uri.to_s
+        file = uri.sub("file://", "")
+        [relative(file), loc.start_line + 1] # rubydex lines are 0-based in 0.4.1
+      rescue StandardError
+        [nil, nil]
+      end
+
+      def extract_declarations(graph, _files)
+        decls = []
+        graph.declarations.each do |d|
+          name = d.name.to_s rescue next
+          next if name.empty?
+
+          kind = case d.class.to_s
+                 when /Class/ then d.is_a?(Rubydex::Module) && !d.is_a?(Rubydex::Class) ? "module" : "class"
+                 when /Module/ then "module"
+                 when /Method/ then "method"
+                 when /Constant/ then "constant"
+                 else d.class.to_s.split("::").last.downcase
+                 end
+          # Normalize: Rubydex::Class < Module etc.
+          kind = "class" if d.is_a?(Rubydex::Class)
+          kind = "module" if d.is_a?(Rubydex::Module) && !d.is_a?(Rubydex::Class)
+          kind = "method" if defined?(Rubydex::Method) && d.is_a?(Rubydex::Method)
+          defs = []
+          begin
+            d.definitions.each do |df|
+              f, line = loc_string(df.location)
+              next unless f && f.start_with?(*["app/", "lib/", "config/"]) || (f && !f.include?("gems/") && !f.start_with?("/"))
+
+              defs << { "file" => f, "line" => line, "kind" => df.class.to_s }
+            end
+          rescue StandardError
+            nil
+          end
+          next if defs.empty? && %w[class module method].include?(kind)
+
+          anc = begin
+            d.ancestors.map(&:name) if d.respond_to?(:ancestors)
+          rescue StandardError
+            nil
+          end
+          members = []
+          if d.respond_to?(:members)
+            begin
+              d.members.each { |m| members << { "name" => m.name.to_s, "kind" => m.class.to_s } }
+            rescue StandardError
+              nil
+            end
+          end
+          decls << { "name" => name, "kind" => kind, "definitions" => defs.sort_by { |x| [x["file"].to_s, x["line"].to_i] },
+                     "ancestors" => anc, "owner" => (d.owner.name rescue nil), "members" => members }
+        end
+        decls.sort_by { |d| d["name"] }
+      rescue StandardError => e
+        raise Error.new("rubydex_index_failed", "Rubydex declaration extraction failed: #{e.class}: #{e.message}")
+      end
+
+      def extract_constant_references(graph)
+        refs = []
+        graph.constant_references.each do |r|
+          f, line = loc_string(r.location)
+          next unless f
+
+          decl = begin
+            r.declaration&.name
+          rescue StandardError
+            nil
+          end
+          refs << { "file" => f, "line" => line, "declaration" => decl, "resolved" => r.is_a?(Rubydex::ResolvedConstantReference) }
+        end
+        refs.sort_by { |r| [r["file"], r["line"]] }
+      rescue StandardError
+        []
+      end
+    end
+  end
+end