augure 0.1.0

data/home/runner/work/augure/augure/lib/augure/knowledge_base.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Augure
+  # Retrieval-augmented knowledge base over a seed corpus of documented
+  # exploitation patterns (ROP Emporium / Protostar / pwnable.tw write-ups).
+  # Pure-Ruby TF-IDF; a consumer can swap in an embedding endpoint, the
+  # interface stays query -> ranked entries.
+  class KnowledgeBase
+    CORPUS_PATH = File.join(__dir__, "kb_corpus.json")
+    PSEUDO_COUNTS = 10
+    MIN_SCORE = 0.05
+
+    Entry = Struct.new(:doc, :score)
+
+    def self.corpus
+      @corpus ||= JSON.parse(File.read(CORPUS_PATH)).freeze
+    end
+
+    # The seed corpus extended with knowledge from loaded technique
+    # packs - entries carry the same shape, so retrieval, priors and
+    # explain see pack techniques like built-in ones.
+    def self.corpus_with(extra)
+      (corpus + extra.to_a).freeze
+    end
+
+    def self.priors
+      accum = Hash.new { |h, k| h[k] = [0.0, 0.0] }
+      corpus.each do |entry|
+        tech = entry["technique"]
+        rate = entry["success_rate"]
+        next if !tech || rate.nil?
+
+        accum[tech][0] += rate * PSEUDO_COUNTS
+        accum[tech][1] += (1 - rate) * PSEUDO_COUNTS
+      end
+      accum
+    end
+
+    def self.transitions
+      corpus.each_with_object(Hash.new { |h, k| h[k] = [] }) do |entry, acc|
+        unlocks = entry["unlocks"]
+        next if !entry["technique"] || !unlocks.is_a?(Array)
+
+        unlocks.each { |u| acc[entry["technique"]] << u unless acc[entry["technique"]].include?(u) }
+      end
+    end
+
+    attr_reader :size
+
+    def initialize(extra: [])
+      @corpus = extra.empty? ? self.class.corpus : self.class.corpus_with(extra)
+      @size = @corpus.size
+      build_index
+    end
+
+    def query(text, technique: nil, n_results: 3)
+      candidates = @corpus.each_with_index.select { |e, _| technique.nil? || e["technique"] == technique }
+      candidates = @corpus.each_with_index.to_a if candidates.empty?
+      return [] if candidates.empty?
+
+      q = encode(text)
+      scored = candidates.filter_map do |entry, i|
+        score = dot(@vectors[i], q)
+        Entry.new(entry, score) if score >= MIN_SCORE
+      end
+      scored.sort_by { |e| -e.score }.first(n_results)
+    end
+
+    private
+
+    def build_index
+      texts = @corpus.map { |e| e["description"] }
+      tokens = texts.map { |t| tokenize(t) }
+      @vocab = {}
+      tokens.each { |tk| tk.each { |w| @vocab[w] ||= @vocab.size } }
+      @df = Array.new(@vocab.size, 0)
+      tokens.each { |tk| tk.uniq.each { |w| @df[@vocab[w]] += 1 } }
+      @idf = @df.map { |df| Math.log((texts.size + 1).to_f / (df + 1)) }
+      @vectors = texts.each_with_index.map { |t, i| encode(t, tf_source: tokens[i]) }
+    end
+
+    def tokenize(text)
+      text.downcase.scan(/[a-z0-9_]+/)
+    end
+
+    # TF (length-normalized) * IDF, L2-normalized. Sparse Hash vector.
+    def encode(text, tf_source: nil)
+      tokens = tf_source || tokenize(text)
+      counts = Hash.new(0.0)
+      tokens.each { |w| counts[@vocab[w]] += 1 if @vocab.key?(w) }
+      total = counts.values.sum
+      return {} if total.zero?
+
+      vec = {}
+      counts.each do |term_idx, tf|
+        val = (tf / total) * @idf[term_idx]
+        vec[term_idx] = val
+      end
+      norm = Math.sqrt(vec.values.sum { |v| v * v }) + 1e-9
+      vec.transform_values { |v| v / norm }
+    end
+
+    def dot(a, b)
+      b.sum { |i, v| a.fetch(i, 0.0) * v }
+    end
+  end
+end

data/home/runner/work/augure/augure/lib/augure/mcts.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Augure
+  # Monte Carlo Tree Search over the technique-transition graph (article 3:
+  # AG -> bandit -> MCTS). Nodes are capability sets, edges are verified
+  # techniques, rollouts score the discounted product of success rates. A
+  # flat bandit cannot value a leak by what it unlocks; this can.
+  class Mcts
+    # technique => [requires, provides, terminal, base_success]
+    STAGE_MODEL = {
+      "fmtstr_leak" => [[], %w[libc_base], false, 0.75],
+      "fmtstr_canary" => [[], %w[canary], false, 0.70],
+      "ret2plt_leak" => [[], %w[libc_base], false, 0.68],
+      "ret2libc" => [%w[libc_base], %w[shell], true, 0.85],
+      "rop" => [%w[libc_base], %w[shell], true, 0.75],
+      # ROP without a libc leak on a PIE target is unreliable (addresses are
+      # guessed). Low success reflects the real-world penalty.
+      "rop_nocontext" => [[], %w[shell], true, 0.25],
+      "ret2plt" => [[], %w[shell], true, 0.75],
+      "shellcode" => [[], %w[shell], true, 0.90],
+      "stack_pivot" => [[], %w[pivot], false, 0.60],
+      # Pivot-gated variants: the real chain only fits after a pivot,
+      # modeling the stack-space constraint.
+      "ret2plt_leak_big" => [%w[pivot], %w[libc_base], false, 0.68],
+      "ret2libc_big" => [%w[pivot libc_base], %w[shell], true, 0.85],
+      # Extended vocabulary: techniques documented by public suites.
+      "ret2csu" => [[], %w[libc_base], false, 0.70],
+      "dlresolve" => [[], %w[shell], true, 0.55],
+      "got_overwrite" => [[], %w[shell], true, 0.65],
+      # PinTheft (RDS zerocopy double-free privesc, V12 Security): a
+      # DOCUMENTED external chain collapsed to its load-bearing spine.
+      "io_uring_register" => [[], %w[iouring], false, 0.90],
+      "rds_pin_steal" => [%w[iouring], %w[pin_underflow], false, 0.70],
+      "page_free" => [%w[pin_underflow], %w[freed_page], false, 0.75],
+      "pagecache_reclaim" => [%w[freed_page], %w[pagecache_ctrl], false, 0.65],
+      "io_uring_write" => [%w[pagecache_ctrl iouring], %w[suid_overwrite], false, 0.70],
+      "suid_exec" => [%w[suid_overwrite], %w[shell], true, 0.90]
+    }.freeze
+
+    DISCOUNT = 0.97
+    MAX_DEPTH = 6
+    UCB_C = 1.41
+
+    class << self
+      def caps
+        Set.new.freeze
+      end
+
+      def available(caps, allowed, model: STAGE_MODEL)
+        model.filter_map do |tech, (req, _, _, _)|
+          tech if allowed.include?(tech) && req.all? { |r| caps.include?(r) }
+        end
+      end
+
+      def transition(caps, tech, model: STAGE_MODEL)
+        caps + model.fetch(tech)[1]
+      end
+
+      # terminal = any capability a terminal:true stage PROVIDES (the model
+      # owns the semantics - the orw pack terminates on flag_read, not
+      # on a shell that never comes). Built-in terminals all provide
+      # "shell", so built-in behaviour is unchanged.
+      def terminal?(caps, model: STAGE_MODEL)
+        model.each_value.any? do |(_, provides, term, _)|
+          term && provides.any? { |c| caps.include?(c) }
+        end
+      end
+
+      def stage(tech, model: STAGE_MODEL)
+        model.fetch(tech)
+      end
+
+      # Built-in stage model + technique-pack transitions (packs only add).
+      def merged_model(packs)
+        merged = STAGE_MODEL.dup
+        Array(packs).each do |pack|
+          m = pack.mcts
+          merged[pack.technique] = [m["requires"], m["provides"], m["terminal"], m["success"]]
+        end
+        merged.freeze
+      end
+
+      # Random rollout: discounted product of success rates down the path.
+      # Reaching shell is necessary but not sufficient: the terminal
+      # technique's own success scales the reward.
+      def rollout(caps, allowed, depth: 0, rng: Random.new, max_depth: MAX_DEPTH, model: STAGE_MODEL)
+        return 1.0 if terminal?(caps, model: model)
+        return 0.0 if depth >= max_depth
+
+        avail = available(caps, allowed, model: model)
+        return 0.0 if avail.empty?
+
+        tech = avail[rand_index(rng, avail.size)]
+        success = stage(tech, model: model)[3]
+        new_caps = transition(caps, tech, model: model)
+        success * (DISCOUNT**depth) * rollout(new_caps, allowed, depth: depth + 1, rng: rng, model: model)
+      end
+
+      # MCTS from an empty capability set: best first move + most-visited path.
+      def plan(allowed, iterations: 2000, seed: nil, model: STAGE_MODEL)
+        rng = seed ? Random.new(seed) : Random.new
+        root = Node.new(caps: caps)
+        root.untried = available(root.caps, allowed, model: model)
+
+        iterations.times do
+          node = root
+          # 1. Selection
+          node = node.children.max_by { |n| n.ucb1(node.visits) } while node.untried.empty? && !node.children.empty?
+          # 2. Expansion. A child whose capability set equals its
+          # parent's adds nothing (the degenerate-tree case: the walk
+          # grows ~iterations deep, selection+backprop O(iterations^2)).
+          # Such nodes are not expanded - the parent absorbs them.
+          unless node.untried.empty?
+            tech = node.untried.pop
+            new_caps = transition(node.caps, tech, model: model)
+            next if new_caps == node.caps && !terminal?(new_caps, model: model)
+
+            child = Node.new(caps: new_caps, technique_used: tech, parent: node)
+            child.untried = terminal?(new_caps) ? [] : available(new_caps, allowed, model: model)
+            node.children << child
+            node = child
+          end
+          # 3. Simulation. An already-terminal expansion node scores its own
+          #    technique's success, not a flat 1.0.
+          reward = if terminal?(node.caps, model: model) && node.technique_used
+            stage(node.technique_used, model: model)[3]
+          else
+            rollout(node.caps, allowed, rng: rng, model: model)
+          end
+          # 4. Backpropagation
+          until node.nil?
+            node.visits += 1
+            node.value += reward
+            node = node.parent
+          end
+        end
+
+        path = []
+        node = root
+        until node.children.empty?
+          node = node.children.max_by(&:visits)
+          path << node.technique_used
+          break if terminal?(node.caps, model: model)
+        end
+        best_first = root.children.max_by(&:visits)&.technique_used
+        [best_first, path]
+      end
+
+      private
+
+      def rand_index(rng, n)
+        (rng.rand * n).to_i.clamp(0, n - 1)
+      end
+    end
+
+    class Node
+      attr_reader :caps, :children
+      attr_accessor :technique_used, :parent, :visits, :value, :untried
+
+      def initialize(caps:, technique_used: nil, parent: nil)
+        @caps = caps.freeze
+        @technique_used = technique_used
+        @parent = parent
+        @children = []
+        @visits = 0
+        @value = 0.0
+        @untried = []
+      end
+
+      def ucb1(parent_visits)
+        return Float::INFINITY if visits.zero?
+
+        (value / visits) +
+          UCB_C * Math.sqrt(Math.log(parent_visits) / visits)
+      end
+    end
+  end
+end

data/home/runner/work/augure/augure/lib/augure/pack.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Augure
+  # A technique pack: ONE new technique, complete, as DATA - rules, KB
+  # entries, MCTS transitions and priors. Written by an operator or an
+  # agent; validated here before it can influence anything.
+  #
+  # The armor (in load order):
+  #   1. constrained condition vocabulary (fact/not_fact/match/cmp)
+  #   2. conditions reference EXISTING predicates only (facts schema +
+  #      built-in derived heads) - a pack cannot invent a fact source
+  #   3. stratification: negation on input facts only
+  #   4. new heads only: a pack never overrides a built-in technique
+  #   5. provenance is mandatory (author + source)
+  #   6. the corpus guard runs in PackLoader (belt and braces on 4)
+  class Pack
+    CONDITION_VOCABULARY = %w[fact not_fact match cmp].freeze
+
+    attr_reader :technique, :author, :source, :rules, :kb, :mcts, :priors, :build, :detection, :mitre
+
+    def self.load_file(path)
+      data = YAML.safe_load_file(path, permitted_classes: [], aliases: false)
+      raise PackError, "#{path}: invalid YAML" unless data.is_a?(Hash)
+
+      load_hash(data)
+    end
+
+    def self.load_hash(data)
+      new(data)
+    end
+
+    def initialize(data)
+      @data = data
+      validate_shape
+      build
+    end
+
+    private
+
+    def reject(message)
+      raise PackError, "#{technique_name || "pack"}: #{message}"
+    end
+
+    def technique_name
+      @data["technique"]
+    end
+
+    def validate_shape
+      @technique = @data["technique"]
+      unless @technique.is_a?(String) && @technique.match?(/\A[a-z0-9_]+\z/)
+        reject "technique name must match [a-z0-9_]+"
+      end
+
+      @author = @data["author"]
+      reject "author is mandatory (provenance is not optional)" unless @author.is_a?(String) && !@author.empty?
+      @source = @data["source"]
+      unless @source.is_a?(String) && !@source.empty?
+        reject "source is mandatory (write-up URL, ticket, anything verifiable)"
+      end
+
+      validate_rules(@data["rules"])
+      validate_kb(@data["kb"])
+      validate_mcts(@data["mcts"])
+      validate_priors(@data["priors"])
+      validate_build(@data["build"])
+      validate_detection(@data["detection"])
+      validate_mitre(@data["mitre"])
+      build_rules
+    end
+
+    def known_predicates
+      @known_predicates ||= Facts::SCHEMA.keys + Rules.all.reject { |r| r.head[0] == Rules::APPLICABLE }.map { |r| r.head[0] }
+    end
+
+    def input_predicates
+      Facts::SCHEMA
+    end
+
+    def built_in_techniques
+      @built_in_techniques ||= Rules.applicable_rules.map { |r| r.head[1] }
+    end
+
+    def validate_rules(rules)
+      reject "rules are mandatory" unless rules.is_a?(Array) && !rules.empty?
+
+      rules.each_with_index do |rule, i|
+        reject "rule #{i}: id mandatory" unless rule["id"].is_a?(String)
+        head = rule["head"]
+        unless head.is_a?(Array) && head[0] == Rules::APPLICABLE && head[1] == @technique
+          reject "rule #{i}: head must be [applicable, <technique>]"
+        end
+        if built_in_techniques.include?(head[1])
+          reject "head overrides a built-in technique (#{head[1]}) - new techniques only"
+        end
+
+        conditions = rule["conditions"]
+        reject "rule #{i}: conditions mandatory" unless conditions.is_a?(Array) && !conditions.empty?
+        conditions.each_with_index do |cond, j|
+          validate_condition(cond, "rule #{i} condition #{j}")
+        end
+      end
+    end
+
+    def validate_condition(cond, label)
+      unless cond.is_a?(Array) && CONDITION_VOCABULARY.include?(cond[0])
+        reject "#{label}: #{cond.inspect} is outside the condition vocabulary #{CONDITION_VOCABULARY.inspect}"
+      end
+
+      kind = cond[0]
+      rel = cond[1]
+      if kind == "not_fact"
+        unless input_predicates.key?(rel)
+          reject "#{label}: not_fact on #{rel.inspect} breaks stratification (negation on input facts only)"
+        end
+      elsif kind == "cmp"
+        reject "#{label}: cmp needs [cmp, rel, op, n]" unless cond.size == 4
+        reject "#{label}: unknown predicate #{rel.inspect}" unless input_predicates.key?(rel)
+        unless Engine::OP.key?(cond[2].to_sym)
+          reject "#{label}: cmp operator #{cond[2].inspect} unknown (#{Engine::OP.keys.join(", ")})"
+        end
+        unless cond[3].is_a?(Integer)
+          reject "#{label}: cmp operand #{cond[3].inspect} must be an integer (the engine compares integer fact values)"
+        end
+      elsif kind == "match"
+        reject "#{label}: match pattern #{cond[3].inspect} must be a string" unless cond[3].is_a?(String)
+        begin
+          Regexp.new(cond[3])
+        rescue RegexpError => e
+          reject "#{label}: match pattern #{cond[3].inspect} is not a valid regex (#{e.message})"
+        end
+      else
+        reject "#{label}: unknown predicate #{rel.inspect}" unless known_predicates.include?(rel)
+      end
+    end
+
+    def validate_kb(entries)
+      reject "kb entries mandatory (the knowledge IS the technique)" unless entries.is_a?(Array) && !entries.empty?
+      entries.each_with_index do |e, i|
+        reject "kb #{i}: id mandatory" unless e["id"].is_a?(String)
+        rate = e["success_rate"]
+        reject "kb #{i}: success_rate must be a number in [0, 1]" unless rate.is_a?(Numeric) && rate.between?(0, 1)
+        reject "kb #{i}: description mandatory" unless e["description"].is_a?(String) && !e["description"].empty?
+      end
+    end
+
+    def validate_mcts(mcts)
+      reject "mcts transitions mandatory" unless mcts.is_a?(Hash)
+      %w[requires provides].each do |k|
+        reject "mcts.#{k} must be an array" unless mcts[k].is_a?(Array)
+      end
+      reject "mcts.terminal must be true or false" unless [true, false].include?(mcts["terminal"])
+      reject "mcts.success must be a number in [0, 1]" unless mcts["success"].is_a?(Numeric) && mcts["success"].between?(
+        0, 1
+      )
+    end
+
+    def validate_priors(priors)
+      return if priors.is_a?(Array) && priors.size == 2 && priors.all?(Numeric)
+
+      reject "priors must be [alpha, beta] (two numbers)"
+    end
+
+    # armor check 8: the optional build: section (the pack teaching the
+    # BUILDER its assembly order) must name its own technique and use
+    # the slot vocabulary only. The consumer (lictor's PayloadBuilder)
+    # interprets the slots; here we gate the vocabulary.
+    BUILD_SLOTS = %w[padding qword dword shellcode chain].freeze
+
+    # armor check 9: the optional detection: section - the DEFENDER
+    # side of the technique (the corpus read backwards). Constrained
+    # channel vocabulary; every entry carries a signature and a note -
+    # a vague hint is not detection content.
+    DETECTION_CHANNELS = %w[wire syslog syscall crash file].freeze
+
+    def validate_detection(detection)
+      return if detection.nil?
+
+      unless detection.is_a?(Array) && !detection.empty?
+        reject "detection: must be a non-empty array"
+      end
+      detection.each_with_index do |e, i|
+        unless e.is_a?(Hash) && DETECTION_CHANNELS.include?(e["channel"])
+          reject "detection #{i}: channel must be from #{DETECTION_CHANNELS.inspect}"
+        end
+        %w[signature note].each do |field|
+          unless e[field].is_a?(String) && !e[field].empty?
+            reject "detection #{i}: #{field} is mandatory (a vague hint is not detection content)"
+          end
+        end
+      end
+      @detection = detection
+    end
+
+    # armor check 10: the optional mitre: mapping - ATT&CK technique
+    # codes (T####[.###]); the export layer (rules --mitre) consumes it.
+    MITRE_CODE = /\AT\d{4}(?:\.\d{3})?\z/
+
+    def validate_mitre(mitre)
+      return if mitre.nil?
+
+      unless mitre.is_a?(Array) && !mitre.empty? && mitre.all? { |c| c.is_a?(String) && c.match?(MITRE_CODE) }
+        reject "mitre: must be an array of ATT&CK technique codes (T1068, T1068.001)"
+      end
+      @mitre = mitre
+    end
+
+    def validate_build(build)
+      return if build.nil?
+
+      unless build.is_a?(Hash) && build["technique"] == @technique
+        reject "build: must name its own technique (#{build.is_a?(Hash) ? build["technique"].inspect : "missing"})"
+      end
+      layout = build["layout"]
+      unless layout.is_a?(Array) && !layout.empty? &&
+          layout.all? { |slot| slot.is_a?(Array) && BUILD_SLOTS.include?(slot[0]) }
+        reject "build: layout must be a non-empty array of slots from #{BUILD_SLOTS.inspect}"
+      end
+      @build = build
+    end
+
+    def build_rules
+      @rules = @data["rules"].map do |rule|
+        conditions = rule["conditions"].map do |cond|
+          normalized = cond.map do |v|
+            if v == true then "true"
+            elsif v == false then "false"
+            else v
+            end
+          end
+          [normalized[0].to_sym, *normalized[1..]]
+        end
+        Rules::Rule.new(
+          id: rule["id"].to_sym, head: rule["head"], conditions: conditions,
+          source: "#{@data["source"]} (pack #{@technique} by #{@author})", origin: @technique
+        )
+      end
+      @kb = @data["kb"]
+      @mcts = @data["mcts"]
+      @priors = @data["priors"].map(&:to_f)
+    end
+  end
+end

data/home/runner/work/augure/augure/lib/augure/pack_loader.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Augure
+  # Loads and screens technique packs. The corpus guard is the armor's
+  # last wall: with the packs loaded, every frozen corpus verdict must
+  # stay identical - a pack that moves an existing decision is refused
+  # at load time, not discovered in production.
+  module PackLoader
+    CORPUS_CACHE = {}
+    BASE_DECISIONS = {}
+
+    module_function
+
+    def load_file(path)
+      Pack.load_file(path)
+    end
+
+    def load_dir(dir)
+      Dir.glob(File.join(dir, "*.{yml,yaml}")).sort.map { |p| Pack.load_file(p) }
+    end
+
+    # Belt and braces: new-heads-only already makes flips structurally
+    # impossible; this proves it on every load.
+    def corpus_guard(packs, corpus_path: nil)
+      corpus_path ||= File.join(__dir__, "ctf_corpus.json")
+      corpus = CORPUS_CACHE[corpus_path] ||= JSON.parse(File.read(corpus_path))
+      # The "before" decisions depend only on the built-in rules and the
+      # base priors - identical across every guard run. Cached.
+      base_priors = Pipeline.default_priors
+      corpus["suites"].values.flatten.each do |entry|
+        before = BASE_DECISIONS[[corpus_path, entry["name"]]] ||=
+          Pipeline.analyze(facts: entry["facts"], priors: base_priors, plan: false)
+        after = Pipeline.analyze(facts: entry["facts"], priors: priors_with(packs, base_priors),
+          packs: packs, plan: false)
+        # A documented pack verdict is not a mover: the frozen entry may
+        # say the built-in table has no answer for this target AND the
+        # pack layer does (entry["pack_verdict"]) - the guard then
+        # checks the pack answer ARRIVES, not that nothing changed. The
+        # check holds only when that pack is among the loaded ones.
+        if entry["pack_verdict"] && packs.any? { |p| p.technique == entry["pack_verdict"] }
+          unless after[:ranking].first == entry["pack_verdict"]
+            raise PackError,
+              "corpus guard: pack(s) #{packs.map(&:technique).join(", ")} fail the documented " \
+              "pack verdict on #{entry["suite"]}/#{entry["name"]} " \
+              "(expected #{entry["pack_verdict"]}, got #{after[:ranking].first}) - refused"
+          end
+          next
+        end
+        # An empty frozen verdict has NOTHING to move: additive packs
+        # extending it are the pack layer working (the documented case
+        # was policed above by pack_verdict when its pack is loaded).
+        next if before[:applicable].empty?
+
+        # Additive packs may extend applicable/ranking with NEW techniques
+        # below the documented top - what they must never do: (1) move an
+        # EXISTING technique's order, (2) take the top-1 of a DOCUMENTED
+        # corpus target (that verdict belongs to the frozen truth; claiming
+        # better on it is a dev-time corpus update, not a runtime pack).
+        # selected is a seeded Thompson draw - stochastic by design, so the
+        # guard compares the deterministic prior-mean ranking only.
+        existing_order = after[:ranking].select { |t| before[:applicable].include?(t) }
+        next if existing_order == before[:ranking] && after[:ranking].first == before[:ranking].first
+
+        raise PackError,
+          "corpus guard: pack(s) #{packs.map(&:technique).join(", ")} move the verdict " \
+          "on #{entry["suite"]}/#{entry["name"]} " \
+          "(#{before[:ranking].first} -> #{after[:ranking].first}) - refused"
+      end
+      packs
+    end
+
+    # Pack priors fill the gaps: a taught technique starts on its
+    # authored prior, but a base table entry (outcome-adapted or
+    # consumer-provided) always wins - the loop stays able to learn.
+    def priors_with(packs, base)
+      return base if packs.nil? || packs.empty?
+
+      merged = base.transform_values(&:dup)
+      packs.each do |pack|
+        merged[pack.technique] = pack.priors.dup unless merged.key?(pack.technique)
+      end
+      merged
+    end
+
+    def mcts_model(packs)
+      return Mcts::STAGE_MODEL if packs.nil? || packs.empty?
+
+      Mcts.merged_model(packs.map(&:mcts))
+    end
+  end
+end

data/home/runner/work/augure/augure/lib/augure/parity.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Augure
+  # Static-parity contract: what the frozen corpus claims about a
+  # documented target vs what the profiler observed on the REAL binary.
+  # The corpus stays the write-up ground truth; parity asserts only what
+  # static ELF analysis can derive, and reports honestly what it cannot:
+  # gadget types outside the profiler's pattern set and source-level
+  # hints (a gets() the binary never imports) are SKIPPED, not failed.
+  class ParityResult
+    attr_reader :target, :missing, :skipped, :checked
+
+    def initialize(target, missing, skipped, checked)
+      @target = target
+      @missing = missing
+      @skipped = skipped
+      @checked = checked
+    end
+
+    def ok? = missing.empty?
+  end
+
+  module Parity
+    EXACT_RELATIONS = %w[nx pie canary relro].freeze
+    SUBSET_RELATIONS = %w[plt target_function].freeze
+
+    module_function
+
+    # observed: a Facts object or a facts string (main binary + shipped
+    # libraries merged by the caller). entry: a corpus hash with "name"
+    # and "facts". supported_gadget_types: the byte-pattern vocabulary of
+    # the profiler at hand (passed in, so this core class stays
+    # profiler-agnostic).
+    def check(observed, entry, supported_gadget_types:)
+      observed = Facts.parse(observed) if observed.is_a?(String)
+      claimed = Facts.parse(entry.fetch("facts"))
+      missing = []
+      skipped = []
+      checked = 0
+
+      claimed.each do |rel, tuple|
+        case rel
+        when *EXACT_RELATIONS, *SUBSET_RELATIONS
+          checked += 1
+          missing << [rel, tuple] unless observed[rel]&.include?(tuple)
+        when "gadget"
+          if supported_gadget_types.include?(tuple[0])
+            checked += 1
+            missing << [rel, tuple] unless observed[rel]&.any? { |t| t[0] == tuple[0] }
+          else
+            skipped << [rel, tuple]
+          end
+        when "vuln_hint"
+          sym = tuple[0].delete_prefix("unsafe_func:")
+          if observed["plt"]&.any? { |t| t == [sym] }
+            checked += 1
+            missing << [rel, tuple] unless observed[rel]&.include?(tuple)
+          else
+            skipped << [rel, tuple]
+          end
+        else
+          skipped << [rel, tuple]
+        end
+      end
+
+      ParityResult.new(entry["name"], missing, skipped, checked)
+    end
+  end
+end