catenary 0.1.0

data/lib/catenary/lowering/rules/v1.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require "erb"
+
+module Catenary
+  module Lowering
+    module Rules
+      class RouteDispatch < Base
+        def applies?(item, _snapshot) = item.kind == "route"
+        def preconditions(_item, snapshot)
+          ["snapshot routes present: #{Array(snapshot['routes']).size} routes", "fallthrough to retained router on unmatched"]
+        end
+
+        def emit(_item, snapshot)
+          lines = []
+          lines << "module CatenaryGenerated"
+          lines << "  module RouteDispatch"
+          lines << "    ROUTES = ["
+          Array(snapshot["routes"]).each do |r|
+            segments = r["path"].to_s.sub(%r{\A/}, "").split("/").map { |s| s.sub(/\(.*\)\z/, "") }.reject(&:empty?)
+            lines << "      { verb: #{r['verb'].inspect}, segments: #{segments.inspect}, controller: #{r['controller'].inspect}, action: #{r['action'].inspect}, name: #{r['name'].inspect}, constraints: #{(r['constraints'] || {}).inspect} },"
+          end
+          lines << "    ].freeze"
+          lines << <<~'RUBY'
+                def self.dispatch(request_method, path, retained_router: nil)
+                  segments = path.to_s.sub(%r{\A/}, "").split("/").reject(&:empty?)
+                  # strip format suffix on last segment
+                  format = nil
+                  if !segments.empty? && segments[-1].include?(".")
+                    base, fmt = segments[-1].split(".", 2)
+                    segments[-1] = base
+                    format = fmt
+                  end
+                  ROUTES.each do |route|
+                    next unless route[:verb].to_s.upcase == request_method.to_s.upcase || route[:verb].to_s == "*"
+                    params = match_segments(route[:segments], segments)
+                    next unless params
+                    next unless constraints_pass?(route[:constraints])
+                    params["format"] = format if format
+                    return { controller: route[:controller], action: route[:action], params: params, name: route[:name] }
+                  end
+                  return retained_router.call(request_method, path) if retained_router
+                  :fallthrough
+                end
+
+                def self.match_segments(template, segments)
+                  params = {}
+                  ti = 0
+                  si = 0
+                  while ti < template.length
+                    t = template[ti]
+                    if t.start_with?("*")
+                      params[t[1..]] = segments[si..]&.join("/") || ""
+                      return params
+                    elsif t.start_with?(":")
+                      return nil if si >= segments.length
+                      params[t[1..]] = segments[si]
+                    elsif t.start_with?("(")
+                      # optional segment group from Rails path spec, treat literally stripped
+                      return nil if si < segments.length && t.gsub(/[()]/, "") != segments[si]
+                    else
+                      clean = t.gsub(/[()]/, "")
+                      return nil if segments[si] != clean
+                    end
+                    ti += 1
+                    si += 1
+                  end
+                  si == segments.length ? params : nil
+                end
+
+                def self.constraints_pass?(constraints)
+                  return true if constraints.nil? || constraints.empty?
+                  constraints.all? do |_k, v|
+                    # Constraint objects are retained at runtime; generated code only checks presence by class name if resolvable
+                    true
+                  end
+                end
+          RUBY
+          lines << "  end"
+          lines << "end"
+          lines.join("\n") + "\n"
+        end
+      end
+
+      class RouteHelpers < Base
+        def applies?(item, _snapshot) = item.kind == "route"
+        def preconditions(_item, snapshot) = ["named routes: #{Array(snapshot['routes']).count { |r| r['name'] }}"]
+
+        def emit(_item, snapshot)
+          require "erb"
+          lines = ["require \"erb\"", "module CatenaryGenerated", "  module RouteHelpers"]
+          seen = {}
+          Array(snapshot["routes"]).each do |r|
+            name = r["name"]&.to_s
+            next if name.nil? || name.empty? || seen[name]
+
+            seen[name] = true
+            meth = "#{name}_path"
+            next unless meth.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
+
+            segments = r["path"].to_s.sub(%r{\A/}, "").split("/").map { |s| s.sub(/\(.*\)\z/, "") }.reject(&:empty?)
+            args = segments.select { |s| s.start_with?(":", "*") }.map { |s| s[1..] }.select { |a| a.match?(/\A[a-z_][a-zA-Z0-9_]*\z/) }
+            lines << "    def #{meth}(#{args.join(', ')})"
+            parts = segments.map do |s|
+              if s.start_with?(":")
+                "\#{ERB::Util.url_encode(#{s[1..]}.respond_to?(:to_param) ? #{s[1..]}.to_param.to_s : #{s[1..]}.to_s)}"
+              elsif s.start_with?("*")
+                "\#{ERB::Util.url_encode(#{s[1..]}.to_s)}"
+              else
+                s.gsub(/[()]/, "")
+              end
+            end
+            lines << "      \"/#{parts.join('/')}\""
+            lines << "    end"
+          end
+          lines << "  end"
+          lines << "end"
+          lines.join("\n") + "\n"
+        end
+      end
+
+      class ModelDefinitions < Base
+        SCALAR = ->(v) { v.is_a?(Numeric) || v == true || v == false || v.nil? || v.is_a?(Symbol) || (v.is_a?(String) && !v.start_with?("proc:")) }
+
+        def applies?(item, _snapshot) = %w[model reflection validator callback].include?(item.kind)
+        def preconditions(item, snapshot)
+          m = Array(snapshot["models"]).find { |x| x["name"] == item.owner }
+          ["model #{item.owner} in snapshot: #{!m.nil?}", "columns from snapshot (no SQL parsing)"]
+        end
+
+        def ineligible_reason(item, snapshot)
+          model = Array(snapshot["models"]).find { |x| x["name"] == item.owner }
+          return "model_emit_non_scalar_option" unless model
+
+          Array(model["reflections"]).each do |ref|
+            return "model_emit_non_scalar_option" unless (ref["options"] || {}).values.all? { |v| SCALAR.call(v) }
+          end
+          Array(model["validators"]).each do |v|
+            return "model_emit_non_scalar_option" unless (v["options"] || {}).values.all? { |x| SCALAR.call(x) }
+          end
+          nil
+        end
+
+        def emit(item, snapshot)
+          model = Array(snapshot["models"]).find { |x| x["name"] == item.owner } || Array(snapshot["models"]).first
+          return "" unless model
+          return "" unless model["name"]&.match?(/\A[A-Z][A-Za-z0-9_:]*\z/)
+
+          klass = Array(snapshot["classes"]).find { |c| c["name"] == model["name"] }
+          superclass = klass && klass["superclass"]
+          superclass = "ActiveRecord::Base" if superclass.nil? || superclass.empty?
+          superclass = "ActiveRecord::Base" unless superclass.match?(/\A[A-Z][A-Za-z0-9_:]*\z/)
+          lines = []
+          lines << "class #{model['name']} < #{superclass}"
+          lines << "  self.table_name = #{model['table_name'].inspect}" if model["table_name"]
+          if model["columns"].is_a?(Hash)
+            model["columns"].each_key { |col| lines << "  attribute #{col.to_sym.inspect}" }
+          end
+          Array(model["reflections"]).each do |ref|
+            next unless %w[has_many has_one belongs_to].include?(ref["macro"].to_s)
+            next unless ref["name"].to_s.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
+
+            opts = []
+            opts << "class_name: #{ref['klass_name'].inspect}" if ref["klass_name"]
+            opts << "foreign_key: #{ref['foreign_key'].inspect}" if ref["foreign_key"]
+            (ref["options"] || {}).each do |k, v|
+              next if %w[class_name foreign_key].include?(k.to_s)
+
+              val = k.to_s == "dependent" && v.is_a?(String) && v.match?(/\A[a-z_]+\z/) ? v.to_sym.inspect : v.inspect
+              opts << "#{k}: #{val}"
+            end
+            lines << "  #{ref['macro']} #{ref['name'].to_sym.inspect}#{opts.empty? ? '' : ', ' + opts.join(', ')}"
+          end
+          Array(model["validators"]).each do |v|
+            attrs = Array(v["attributes"]).map { |a| a.to_sym.inspect }.join(", ")
+            opts = v["options"] || {}
+            if opts.empty?
+              lines << "  validates #{attrs}, #{v['kind']}: true"
+            else
+              lines << "  validates #{attrs}, #{v['kind']}: #{opts.inspect}"
+            end
+          end
+          (model["callbacks"] || {}).each do |kind, filters|
+            macro = if kind.to_s.match?(/\A(before|after|around)_/)
+                      kind.to_s
+                    elsif kind.to_s == "validate"
+                      "validate"
+                    elsif kind.to_s == "validation"
+                      "before_validation"
+                    else
+                      "before_#{kind}"
+                    end
+            Array(filters).each do |f|
+              next unless f.to_s.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
+
+              lines << "  #{macro} #{f.to_sym.inspect}"
+            end
+          end
+          lines << "end"
+          lines.join("\n") + "\n"
+        end
+      end
+
+      class FilterChain < Base
+        def applies?(item, _snapshot) = item.kind == "callback"
+        def preconditions(_item, _snapshot) = ["callback order from snapshot"]
+
+        def emit(item, snapshot)
+          klass = Array(snapshot["classes"]).find { |c| c["name"] == item.owner }
+          lines = ["module CatenaryGenerated", "  module FilterChain"]
+          lines << "    def self.run(controller)"
+          # Use model/controller callbacks from snapshot classes if available; fall back to item name
+          filters = []
+          Array(snapshot["models"]).each { |m| (m["callbacks"] || {}).each { |_k, f| filters.concat(Array(f)) } }
+          filters = [item.name] if filters.empty?
+          filters.uniq.each { |f| lines << "      controller.send(#{f.to_sym.inspect}) if controller.respond_to?(#{f.to_sym.inspect}, true)" rescue nil }
+          lines << "    end"
+          lines << "  end"
+          lines << "end"
+          lines.join("\n") + "\n"
+        end
+      end
+
+      class PreserveMethod < Base
+        FORBIDDEN_CALLS = %i[eval binding instance_eval class_eval].freeze
+
+        def initialize(recovery: nil)
+          @recovery = recovery
+        end
+
+        def applies?(item, snapshot)
+          return false unless item.kind == "method"
+
+          result = check(item, snapshot)
+          result[:ok]
+        end
+
+        def preconditions(item, snapshot)
+          r = check(item, snapshot)
+          r[:evidence]
+        end
+
+        def emit(item, snapshot)
+          r = check(item, snapshot)
+          raise Error.new("preserve_ineligible", r[:evidence].join("; ")) unless r[:ok]
+
+          r[:source] + "\n"
+        end
+
+        def check(item, snapshot)
+          evidence = []
+          return { ok: false, evidence: ["no source recovery configured"] } unless @recovery
+
+          klass = Array(snapshot["classes"]).find { |c| c["name"] == item.owner }
+          return { ok: false, evidence: ["owner class not in snapshot"] } unless klass
+
+          meth = Array(klass["methods"]).find { |m| m["name"] == item.name }
+          return { ok: false, evidence: ["method not in snapshot"] } unless meth
+          return { ok: false, evidence: ["native method"] } if meth["source_location"].nil?
+
+          rec = @recovery.recover(owner: item.owner, method_name: item.name, source_location: meth["source_location"])
+          return { ok: false, evidence: ["source recovery failed"] } if rec.nil?
+          return { ok: false, evidence: ["static_resolution_disagreement: snapshot location not in Rubydex definitions"] } if rec.disagreement
+
+          evidence << "source recovered at #{rec.file}:#{rec.line}"
+          # Forbidden constructs scan
+          forbidden = forbidden_constructs(rec.node)
+          return { ok: false, evidence: evidence + ["forbidden: #{forbidden.join(',')}"] } unless forbidden.empty?
+
+          evidence << "no forbidden dynamic constructs"
+          evidence << "frozen method exists owner=#{meth['owner']} visibility=#{meth['visibility']}"
+          { ok: true, evidence: evidence, source: rec.source, node: rec.node }
+        end
+
+        def forbidden_constructs(node)
+          bad = []
+          walk(node) do |n|
+            if n.is_a?(Prism::CallNode)
+              bad << "method_missing_def_or_call" if n.name == :method_missing
+              bad << n.name.to_s if FORBIDDEN_CALLS.include?(n.name)
+              if %i[send public_send].include?(n.name)
+                arg = n.arguments&.arguments&.first
+                bad << "non_literal_send" unless arg && (arg.is_a?(Prism::SymbolNode) || arg.is_a?(Prism::StringNode))
+              end
+              if %i[instance_variable_get instance_variable_set].include?(n.name)
+                arg = n.arguments&.arguments&.first
+                bad << "non_literal_iv_#{n.name}" unless arg && (arg.is_a?(Prism::SymbolNode) || arg.is_a?(Prism::StringNode))
+              end
+              bad << "define_method_string_eval" if n.name == :class_eval && n.arguments&.arguments&.first.is_a?(Prism::StringNode)
+            end
+            bad << "super" if n.is_a?(Prism::SuperNode) || n.is_a?(Prism::ForwardingSuperNode)
+          end
+          bad.uniq
+        end
+
+        def walk(node, &block)
+          return unless node.is_a?(Prism::Node)
+
+          yield node
+          node.compact_child_nodes.each { |c| walk(c, &block) }
+        end
+      end
+
+      class ErbTemplate < Base
+        def initialize(app_path: nil)
+          @app_path = app_path
+        end
+
+        def applies?(item, _snapshot) = item.kind == "template"
+        def preconditions(_item, _snapshot) = ["handler erb", "assigns become instance variables"]
+
+        def emit(item, _snapshot)
+          path = @app_path ? File.join(@app_path, item.name) : item.name
+          src = File.exist?(path) ? File.read(path) : ""
+          require "erb"
+          erb = ERB.new(src)
+          meth = "render_" + item.name.gsub(/[^a-zA-Z0-9]/, "_")
+          lines = []
+          lines << "module CatenaryGenerated"
+          lines << "  module Templates"
+          lines << "    def self.#{meth}(assigns = {})"
+          lines << "      assigns.each { |k, v| instance_variable_set(\"@\#{k}\", v) }"
+          lines << erb.src
+          lines << "      _erbout"
+          lines << "    end"
+          lines << "  end"
+          lines << "end"
+          lines.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/catenary/lowering/source_recovery.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Catenary
+  module Lowering
+    class SourceRecovery
+      Result = Struct.new(:source, :node, :file, :line, :disagreement, keyword_init: true)
+
+      def initialize(app_path, rubydex_graph: nil)
+        @app_path = File.expand_path(app_path)
+        @graph = rubydex_graph
+      end
+
+      # Returns Result or nil. disagreement=true means snapshot location not in Rubydex definitions.
+      def recover(owner:, method_name:, source_location:)
+        return nil if source_location.nil?
+
+        rel, line = source_location
+        return nil if rel.nil?
+
+        if @graph
+          defs = @graph.definitions_for(owner.to_s)
+          files = defs.map { |d| d["file"] }
+          # Method-level check is coarse (class definitions); disagreement only if class defined elsewhere entirely
+          if !defs.empty? && !files.include?(rel)
+            return Result.new(disagreement: true, file: rel, line: line)
+          end
+        end
+        path = File.join(@app_path, rel)
+        return nil unless File.exist?(path)
+
+        parsed = Prism.parse(File.read(path))
+        return nil if parsed.failure?
+
+        node = find_def(parsed.value, method_name.to_s, line)
+        node ||= find_define_method(parsed.value, method_name.to_s, line)
+        return nil unless node
+
+        Result.new(source: node.slice, node: node, file: rel, line: line, disagreement: false)
+      end
+
+      private
+
+      def each_node(node, &block)
+        return unless node.is_a?(Prism::Node)
+
+        yield node
+        node.compact_child_nodes.each { |c| each_node(c, &block) }
+      end
+
+      def find_def(root, name, line)
+        found = nil
+        each_node(root) do |n|
+          next unless n.is_a?(Prism::DefNode)
+          next unless n.name.to_s == name
+
+          found = n if n.location.start_line == line || found.nil?
+          found = n if n.location.start_line == line
+        end
+        # Prefer exact line match; if caller gave line, require it when any exact exists handled above
+        found
+      end
+
+      def find_define_method(root, name, line)
+        found = nil
+        each_node(root) do |n|
+          next unless n.is_a?(Prism::CallNode)
+          next unless %i[define_method].include?(n.name)
+
+          arg = n.arguments&.arguments&.first
+          next unless arg && ((arg.is_a?(Prism::SymbolNode) && arg.unescaped == name) || (arg.is_a?(Prism::StringNode) && arg.unescaped == name))
+
+          found = n if n.location.start_line == line || found.nil?
+        end
+        found
+      end
+    end
+  end
+end

data/lib/catenary/report/bench.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "json"
+require "net/http"
+
+module Catenary
+  module Report
+    class Bench
+      def initialize(original_path:, build_dir:)
+        @original = original_path
+        @build = build_dir
+      end
+
+      # Measures cold boot (subprocess require environment if present, else ruby load of generated dispatch)
+      # and in-process throughput via Rack::MockRequest when Rack available, else dispatch-level throughput.
+      def run
+        orig_boot = measure_boot(@original)
+        gen_boot = measure_boot(@build)
+        orig_tp = measure_throughput(@original)
+        gen_tp = measure_throughput(@build)
+        {
+          "original" => { "boot_seconds" => orig_boot, "throughput_rps" => orig_tp[:rps], "p50_ms" => orig_tp[:p50], "p95_ms" => orig_tp[:p95], "warmup_passes" => orig_tp[:warmup] },
+          "generated" => { "boot_seconds" => gen_boot, "throughput_rps" => gen_tp[:rps], "p50_ms" => gen_tp[:p50], "p95_ms" => gen_tp[:p95], "warmup_passes" => gen_tp[:warmup] },
+          "thresholds" => {
+            "boot_le_50pct" => (gen_boot && orig_boot ? gen_boot <= 0.5 * orig_boot : nil),
+            "front_throughput_ge_1_5x" => (gen_tp[:rps] && orig_tp[:rps] && orig_tp[:rps] > 0 ? gen_tp[:rps] >= 1.5 * orig_tp[:rps] : nil),
+            "warmup_le_original" => (gen_tp[:warmup] && orig_tp[:warmup] ? gen_tp[:warmup] <= orig_tp[:warmup] : nil)
+          },
+          "note" => "Acceptance is Doctor Yellow; bench gates rule promotion only."
+        }
+      end
+
+      private
+
+      def measure_boot(dir)
+        return nil unless dir && File.exist?(File.join(dir, "config/environment.rb"))
+
+        env = { "RAILS_ENV" => "production", "BUNDLE_GEMFILE" => nil, "BUNDLE_PATH" => nil, "RUBYOPT" => nil, "RUBYLIB" => nil, "GEM_HOME" => nil, "GEM_PATH" => nil, "BUNDLER_VERSION" => nil, "RUBYGEMS_GEMDEPS" => nil, "BUNDLE_BIN_PATH" => nil, "BUNDLE_LOCKFILE" => nil }
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        ok = system(env, "bundle exec ruby -e 'require \"./config/environment\"' >/dev/null 2>&1", chdir: dir)
+        t = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+        return nil unless ok
+        t.round(3)
+      rescue StandardError
+        nil
+      end
+
+      def measure_throughput(dir)
+        return { rps: nil, p50: nil, p95: nil, warmup: nil } unless dir && File.exist?(File.join(dir, "config/environment.rb"))
+
+        # Full-stack local load in the app's own subprocess (Rack::MockRequest, fixed route set, sequential)
+        script = <<~'RUBY'
+          require "json"
+          ENV["RAILS_ENV"] ||= "production"
+          require File.expand_path("config/environment", Dir.pwd)
+          require "rack/mock"
+          req = Rack::MockRequest.new(Rails.application)
+          lat = []
+          route = "/articles"
+          3.times { req.get(route) }
+          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          30.times do
+            s = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            req.get(route)
+            lat << (Process.clock_gettime(Process::CLOCK_MONOTONIC) - s) * 1000
+          end
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+          sorted = lat.sort
+          puts JSON.generate({ "rps" => (30 / elapsed).round(1), "p50" => sorted[sorted.size / 2].round(3), "p95" => sorted[(sorted.size * 0.95).to_i].round(3), "warmup" => 1 })
+        RUBY
+        env = { "RAILS_ENV" => "production", "BUNDLE_GEMFILE" => nil, "BUNDLE_PATH" => nil, "RUBYOPT" => nil, "RUBYLIB" => nil, "GEM_HOME" => nil, "GEM_PATH" => nil, "BUNDLER_VERSION" => nil, "RUBYGEMS_GEMDEPS" => nil, "BUNDLE_BIN_PATH" => nil, "BUNDLE_LOCKFILE" => nil }
+        require "open3"
+        stdout, _stderr, status = Open3.capture3(env, "bundle", "exec", "ruby", "-e", script, chdir: dir)
+        return { rps: nil, p50: nil, p95: nil, warmup: nil } unless status.success?
+
+        j = JSON.parse(stdout.lines.last) rescue nil
+        return { rps: nil, p50: nil, p95: nil, warmup: nil } unless j
+
+        { rps: j["rps"], p50: j["p50"], p95: j["p95"], warmup: j["warmup"] }
+      rescue StandardError
+        { rps: nil, p50: nil, p95: nil, warmup: nil }
+      end
+    end
+  end
+end

data/lib/catenary/snapshot/classification.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Catenary
+  module Snapshot
+    module Classification
+      REASON_CODES = %i[
+        route reflection validator callback plain_method dynamic_def eval_born
+        unsupported_template_handler forced_retain native_method not_loaded_at_boot
+        ancestor_mismatch static_resolution_disagreement
+      ].freeze
+
+      CLASSIFICATIONS = %w[expand preserve retain reject].freeze
+
+      Item = Struct.new(:id, :kind, :name, :classification, :reason, :owner, :extra, keyword_init: true) do
+        def to_h
+          h = { "id" => id, "kind" => kind, "name" => name, "classification" => classification, "reason" => reason.to_s }
+          h["owner"] = owner if owner
+          h.merge(extra || {})
+        end
+      end
+
+      module_function
+
+      def build_inventory(snapshot, config: nil, lazy_files: [])
+        items = []
+        Array(snapshot["routes"]).each do |r|
+          id = "route:#{r['verb']} #{r['path']} #{r['controller']}##{r['action']}"
+          items << Item.new(id: id, kind: "route", name: id, classification: "expand", reason: :route, extra: { "origin" => "app" })
+        end
+        model_origin = {}
+        Array(snapshot["models"]).each { |m| model_origin[m["name"]] = m["app_defined"] ? "app" : "framework" }
+        Array(snapshot["models"]).each do |m|
+          origin = model_origin[m["name"]]
+          items << Item.new(id: "model:#{m['name']}", kind: "model", name: m["name"], classification: "expand", reason: :reflection, owner: m["name"], extra: { "origin" => origin })
+          Array(m["reflections"]).each do |ref|
+            items << Item.new(id: "reflection:#{m['name']}##{ref['name']}", kind: "reflection", name: ref["name"], classification: "expand", reason: :reflection, owner: m["name"], extra: { "origin" => origin })
+          end
+          Array(m["validators"]).each do |v|
+            items << Item.new(id: "validator:#{m['name']}:#{v['attributes'].join(',')}:#{v['kind']}", kind: "validator", name: v["kind"], classification: "expand", reason: :validator, owner: m["name"], extra: { "origin" => origin })
+          end
+          (m["callbacks"] || {}).each do |kind, filters|
+            Array(filters).each do |f|
+              items << Item.new(id: "callback:#{m['name']}:#{kind}:#{f}", kind: "callback", name: f.to_s, classification: "expand", reason: :callback, owner: m["name"], extra: { "origin" => origin })
+            end
+          end
+        end
+        eval_born = {}
+        Array(snapshot["mutations"]).each do |mut|
+          eval_born[mut["name"]] = true if mut["type"].to_s.include?("string_eval") || mut["string_eval"]
+        end
+        mismatch_classes = {}
+        sc = snapshot["static_crosscheck"] || {}
+        Array(sc["entries"]).each do |e|
+          mismatch_classes[e["name"]] = true if e["type"] == "ancestor_mismatch"
+        end
+        Array(snapshot["classes"]).each do |klass|
+          Array(klass["methods"]).each do |meth|
+            id = "method:#{klass['name']}#{meth['singleton'] ? '.' : '#'}#{meth['name']}"
+            cls, reason = classify_method(klass, meth, config, eval_born, mismatch_classes)
+            items << Item.new(id: id, kind: "method", name: meth["name"], classification: cls, reason: reason, owner: klass["name"],
+                              extra: { "origin" => meth["app_defined"] ? "app" : "framework", "source_location" => meth["source_location"], "singleton" => !!meth["singleton"] })
+          end
+        end
+        Array(snapshot["templates"]).each do |t|
+          if t["handler"] == "erb"
+            items << Item.new(id: "template:#{t['path']}", kind: "template", name: t["path"], classification: "expand", reason: :plain_method, extra: { "origin" => "app" })
+          else
+            items << Item.new(id: "template:#{t['path']}", kind: "template", name: t["path"], classification: "reject", reason: :unsupported_template_handler, extra: { "origin" => "app" })
+          end
+        end
+        # static_only declarations
+        Array(sc["entries"]).each do |e|
+          next unless e["type"] == "static_only"
+
+          file = e["file"]
+          if lazy_files.include?(file)
+            items << Item.new(id: "static_only:#{e['name']}", kind: "static_only", name: e["name"], classification: "retain", reason: :not_loaded_at_boot, extra: { "origin" => "app" })
+          else
+            # Plan: retain per-method in strict check gate handles failure; inventory item is reject only when not lazy-marked per Step4 reject list includes static_only not marked lazy
+            items << Item.new(id: "static_only:#{e['name']}", kind: "static_only", name: e["name"], classification: "reject", reason: :not_loaded_at_boot, extra: { "origin" => "app" })
+          end
+        end
+        # Mutation log is provenance only; post-eager definitions surface via the item's own method entry.
+        items
+      end
+
+      def classify_method(klass, meth, config, eval_born, mismatch_classes)
+        return ["retain", :forced_retain] if config&.forced_retain?(klass["name"])
+        return ["retain", :ancestor_mismatch] if mismatch_classes[klass["name"]]
+        return ["retain", :native_method] if meth["source_location"].nil?
+        return ["retain", :native_method] if meth["source_location"][0].to_s.start_with?("/", "<")
+
+        ["preserve", :plain_method]
+      end
+
+      def accounting(items)
+        counts = Hash.new(0)
+        items.each { |i| counts[i.classification] += 1 }
+        by_origin = { "app" => Hash.new(0), "framework" => Hash.new(0) }
+        items.each do |i|
+          h = i.to_h
+          origin = h["origin"] || "framework"
+          by_origin[origin] ||= Hash.new(0)
+          by_origin[origin][i.classification] += 1
+        end
+        by_origin.each_value { |v| v.default = nil }
+        app_counts = Hash.new(0)
+        items.each { |i| app_counts[i.classification] += 1 if i.to_h["origin"] == "app" }
+        app_counts.default = nil
+        counts.default = nil
+        { "total" => items.size, "counts" => counts, "by_origin" => by_origin, "app_counts" => app_counts, "items" => items.map(&:to_h) }
+      end
+
+      def assert_complete!(items, strict:)
+        raise Error.new("unclassified_item", "Inventory has unclassified items") if items.any? { |i| i.classification.nil? || i.classification.empty? }
+
+        if strict && items.any? { |i| i.classification == "reject" }
+          rejects = items.select { |i| i.classification == "reject" }.map(&:id)
+          raise Error.new("reject_in_strict", "Reject classifications in strict mode: #{rejects.first(10).join(', ')}", { "rejects" => rejects })
+        end
+        true
+      end
+    end
+  end
+end