moult 0.1.0

data/lib/moult/duplication/confidence.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Moult
+  module Duplication
+    # The per-finding confidence model for duplication — the duplication slice's
+    # realisation of Moult's protected confidence API. It answers a deliberately
+    # humble question: *how confident are we that this clone group is genuine,
+    # consolidatable duplication* rather than an incidental structural rhyme? It
+    # never asserts certainty; every contributing factor is recorded as a {Reason}
+    # so the judgement is auditable.
+    #
+    # {assess} is a pure function of the signals flay hands us (already extracted
+    # by {Clones}): no IO, no flay objects. That keeps it trivially unit-testable
+    # and lets the scoring be pinned against hand-built inputs — drift is a bug,
+    # the same treatment {ABC} and the coverage {Resolver} get.
+    module Confidence
+      CATEGORY = "duplication"
+
+      # Base likelihood before any adjustment, keyed by kind. An *identical*
+      # (byte-for-byte) match is near-certain duplication; a merely *similar*
+      # match (names/literals differ) is weaker and could be parallel-by-design.
+      BASE = {identical: 0.6, similar: 0.45}.freeze
+
+      # A structurally-similar (not identical) match never reaches high confidence:
+      # shared shape is not proof of shared intent.
+      SIMILAR_CAP = 0.75
+
+      # Larger duplicated structures are far less likely to be coincidental.
+      MASS_LARGE = 100
+      MASS_MEDIUM = 40
+
+      # sexp node types that are whole, cleanly-extractable definitions. A
+      # duplicated whole method/class is the least ambiguous "consolidate me".
+      WHOLE_DEFINITION = %w[defn defs class module sclass].freeze
+
+      # One auditable contribution to a finding's confidence. Mirrors the shared
+      # rule/delta/detail reason shape used across Moult's contracts; kept local so
+      # the duplication slice does not couple to the dead-code Confidence module.
+      Reason = Struct.new(:rule, :delta, :detail) do
+        def to_h
+          {rule: rule.to_s, delta: delta, detail: detail}
+        end
+      end
+
+      # The graded result: a confidence in [0, 1] and the reasons behind it.
+      Assessment = Struct.new(:confidence, :reasons)
+
+      module_function
+
+      # @param kind [Symbol] :identical or :similar
+      # @param mass [Integer] flay's mass for the duplicated node
+      # @param occurrence_count [Integer] number of sites (>= 2)
+      # @param node_type [String] flay sexp type, e.g. "defn", "call"
+      # @return [Assessment]
+      def assess(kind:, mass:, occurrence_count:, node_type:)
+        base = BASE.fetch(kind, BASE[:similar])
+        reasons = [Reason.new(rule: :base_score, delta: base, detail: base_detail(kind))]
+
+        mass_contribution = mass_reason(mass)
+        reasons << mass_contribution if mass_contribution
+        reasons << Reason.new(rule: :many_occurrences, delta: 0.07, detail: "duplicated across #{occurrence_count} locations") if occurrence_count >= 3
+        reasons << Reason.new(rule: :whole_definition, delta: 0.08, detail: "duplicates a whole #{node_type}") if WHOLE_DEFINITION.include?(node_type)
+
+        raw = reasons.sum(&:delta)
+        if kind == :similar && raw > SIMILAR_CAP
+          reasons << Reason.new(rule: :similar_cap, delta: 0.0, detail: "structural similarity is not proof of duplication; capped at #{SIMILAR_CAP}")
+          raw = SIMILAR_CAP
+        end
+
+        Assessment.new(confidence: raw.clamp(0.0, 1.0).round(2), reasons: reasons)
+      end
+
+      def base_detail(kind)
+        if kind == :identical
+          "identical structural match (byte-for-byte)"
+        else
+          "structurally-similar match (names/literals differ)"
+        end
+      end
+
+      # Bucketed so the contribution is stable and pinnable regardless of the
+      # run's configurable --min-mass.
+      def mass_reason(mass)
+        if mass >= MASS_LARGE
+          Reason.new(rule: :large_mass, delta: 0.2, detail: "large duplicated mass (#{mass})")
+        elsif mass >= MASS_MEDIUM
+          Reason.new(rule: :medium_mass, delta: 0.1, detail: "moderate duplicated mass (#{mass})")
+        end
+      end
+    end
+  end
+end

data/lib/moult/duplication.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Moult
+  # Orchestrates the duplication analysis: it asks the {Clones} adapter (flay) for
+  # every structural clone group, attributes each occurrence to its enclosing
+  # method (best-effort, for the cross-analysis join), and grades each group
+  # through the pure {Duplication::Confidence} model. The result is a ranked
+  # {DuplicationReport} of confidence-graded clone groups — never an assertion
+  # that duplication is certainly removable.
+  #
+  # This is the only layer that knows where the facts come from; {Confidence}
+  # stays a pure function of the extracted signals so it can be pinned in
+  # isolation.
+  module Duplication
+    module_function
+
+    # @param root [String] absolute analysis root
+    # @param files [Array<String>] absolute Ruby file paths to scan
+    # @param min_mass [Integer] flay mass threshold; smaller fragments are ignored
+    # @param fuzzy [Boolean] include near-matches (off by default)
+    # @param min_confidence [Float] drop findings below this confidence
+    # @return [DuplicationReport]
+    def build_report(root:, files:, min_mass: Clones::DEFAULT_MIN_MASS, fuzzy: false,
+      min_confidence: 0.0, git_ref: nil, generated_at: nil)
+      clones = Clones.detect(root: root, files: files, min_mass: min_mass, fuzzy: fuzzy)
+      methods = MethodIndex.new(root: root, files: files)
+
+      findings = clones.sets.map { |set| finding_for(set, methods) }
+      findings.select! { |f| f.confidence >= min_confidence }
+      # Highest-confidence first, then heaviest, with node type as a deterministic
+      # tie-break so output is stable across runs.
+      findings.sort_by! { |f| [-f.confidence, -f.mass, f.node_type] }
+
+      DuplicationReport.new(
+        root: root,
+        findings: findings,
+        git_ref: git_ref,
+        generated_at: generated_at,
+        backend: clones.backend,
+        backend_version: clones.backend_version,
+        min_mass: clones.min_mass,
+        fuzzy: clones.fuzzy
+      )
+    end
+
+    def finding_for(set, methods)
+      assessment = Confidence.assess(
+        kind: set.kind,
+        mass: set.mass,
+        occurrence_count: set.occurrences.size,
+        node_type: set.node_type
+      )
+      occurrences = set.occurrences.map do |occ|
+        DuplicationReport::Occurrence.new(
+          symbol_id: methods.symbol_id_at(occ.path, occ.line),
+          path: occ.path,
+          line: occ.line,
+          fuzzy: occ.fuzzy
+        )
+      end
+      DuplicationReport::Finding.new(
+        confidence: assessment.confidence,
+        kind: set.kind,
+        node_type: set.node_type,
+        mass: set.mass,
+        reasons: assessment.reasons,
+        occurrences: occurrences
+      )
+    end
+
+    # Best-effort line -> enclosing-method resolution, reusing the Prism {Parser}
+    # so the minted ids are byte-identical to the hotspots/deadcode join keys.
+    # flay reports a clone's start line only; we attribute it to the innermost
+    # method whose span contains that line. Files are parsed lazily and memoised;
+    # a fragment outside any method (top-level code, a whole class) resolves to nil.
+    class MethodIndex
+      def initialize(root:, files:)
+        @abs_by_rel = files.to_h { |abs| [SymbolId.relative_path(abs, root), abs] }
+        @cache = {}
+      end
+
+      # @return [String, nil] symbol_id of the innermost containing method, or nil
+      def symbol_id_at(rel_path, line)
+        method = enclosing_method(rel_path, line)
+        return nil unless method
+        SymbolId.for(path: rel_path, start_line: method.span.start_line, fqname: method.name)
+      end
+
+      private
+
+      def enclosing_method(rel_path, line)
+        methods_for(rel_path)
+          .select { |m| line.between?(m.span.start_line, m.span.end_line) }
+          .min_by { |m| m.span.end_line - m.span.start_line }
+      end
+
+      def methods_for(rel_path)
+        @cache[rel_path] ||= parse(rel_path)
+      end
+
+      def parse(rel_path)
+        abs = @abs_by_rel[rel_path]
+        return [] unless abs
+        Parser.parse_file(abs)
+      rescue
+        []
+      end
+    end
+  end
+end
+
+require_relative "duplication/confidence"

data/lib/moult/duplication_report.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Moult
+  # The serialized result model for `moult duplication` (schema/duplication.schema.json),
+  # sibling to {DeadCodeReport} and {CoverageReport}. It owns the JSON envelope and
+  # leaves the other protected contracts untouched. Each {Finding} is a confidence-
+  # graded clone group carrying its {Reason}s and {Occurrence}s; nothing here asserts
+  # that duplication is certainly removable.
+  class DuplicationReport
+    # Bump only on a breaking change to the serialized shape.
+    SCHEMA_VERSION = 1
+
+    # One site of a clone group. +symbol_id+ is the best-effort enclosing method
+    # (the shared cross-analysis join key), nil when the fragment is not inside a
+    # known method (top-level code, or a duplicated whole class). +line+ is flay's
+    # reported start line — line granularity is all flay provides.
+    Occurrence = Struct.new(:symbol_id, :path, :line, :fuzzy) do
+      def to_h
+        {symbol_id: symbol_id, path: path, line: line, fuzzy: fuzzy}
+      end
+    end
+
+    # A confidence-graded clone group. Carries its reasons so no claim is made
+    # without a recorded justification.
+    Finding = Struct.new(:confidence, :kind, :node_type, :mass, :reasons, :occurrences) do
+      def to_h
+        {
+          category: Duplication::Confidence::CATEGORY,
+          confidence: confidence,
+          kind: kind.to_s,
+          node_type: node_type,
+          mass: mass,
+          reasons: reasons.map(&:to_h),
+          occurrences: occurrences.map(&:to_h)
+        }
+      end
+    end
+
+    attr_reader :root, :findings, :git_ref, :generated_at,
+      :backend, :backend_version, :min_mass, :fuzzy
+
+    # @param root [String] absolute analysis root
+    # @param findings [Array<Finding>] ranked, highest-confidence first
+    # @param backend [String] detector backend name (e.g. "flay")
+    # @param backend_version [String, nil] backend gem version
+    # @param min_mass [Integer] the mass threshold used
+    # @param fuzzy [Boolean] whether near-matches were included
+    def initialize(root:, findings:, git_ref: nil, generated_at: nil,
+      backend: "flay", backend_version: nil, min_mass: nil, fuzzy: false)
+      @root = root
+      @findings = findings
+      @git_ref = git_ref
+      @generated_at = generated_at
+      @backend = backend
+      @backend_version = backend_version
+      @min_mass = min_mass
+      @fuzzy = fuzzy
+    end
+
+    # @return [Hash] aggregate counts across all clone groups
+    def summary
+      {
+        sets: findings.size,
+        occurrences: findings.sum { |f| f.occurrences.size },
+        total_mass: findings.sum(&:mass)
+      }
+    end
+
+    def to_h
+      {
+        schema_version: SCHEMA_VERSION,
+        tool: {name: "moult", version: Moult::VERSION},
+        analysis: {
+          root: root,
+          git_ref: git_ref,
+          generated_at: generated_at,
+          detector: {
+            backend: backend,
+            backend_version: backend_version,
+            min_mass: min_mass,
+            fuzzy: fuzzy
+          }
+        },
+        summary: summary,
+        findings: findings.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/moult/flag_scanner.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Moult
+  # The OpenFeature flag-evaluation SCANNER — the *only* file that knows the
+  # OpenFeature client call shape, so a future SDK or provider shift is a swap,
+  # not a rewrite (the same isolation {Clones} gives flay and {Boundaries::Packwerk}
+  # gives packwerk). It is a pure Prism scan over source, shaped like
+  # {SymbolScanner}: there is no external-tool output to ingest here.
+  #
+  # OpenFeature (github.com/open-feature/ruby-sdk, gem +openfeature-sdk+) is the
+  # provider-agnostic feature-flag *standard*: a client is built via
+  # +OpenFeature::SDK.build_client+ and flags are evaluated with
+  # +client.fetch_<type>_value(flag_key:, default_value:, evaluation_context:)+
+  # (and the +fetch_<type>_details+ variants). Scanning that client surface catches
+  # flag usage behind *any* provider (flagd, LaunchDarkly, GO Feature Flag, ...).
+  #
+  # We detect by AST only and take NO dependency on the openfeature-sdk gem — we
+  # read the call shape, we never call the SDK. A call is an OpenFeature evaluation
+  # when its method name is one of the known +fetch_*+ names AND it passes a
+  # +flag_key:+ keyword argument (the keyword uniquely disambiguates it from any
+  # unrelated same-named method, since the receiver is a runtime value).
+  module FlagScanner
+    # Provenance recorded in the report's `analysis.scanner` block. The swap point:
+    # retarget these (and {METHOD_VALUE_TYPES}) for a different SDK/standard.
+    TARGET = "openfeature"
+    SDK_GEM = "openfeature-sdk"
+    CLIENT_BUILDER = "OpenFeature::SDK.build_client"
+
+    # The fetch_<type>_(value|details) method names mapped to the contract's
+    # value_type. integer/float collapse to "number" (the value_type enum is
+    # coarser than the SDK's fetch types); the precise method name is kept on each
+    # call site so nothing is lost.
+    FETCH_TYPES = {
+      "boolean" => "boolean",
+      "string" => "string",
+      "number" => "number",
+      "integer" => "number",
+      "float" => "number",
+      "object" => "object"
+    }.freeze
+
+    METHOD_VALUE_TYPES = FETCH_TYPES.each_with_object({}) do |(fetch_type, value_type), acc|
+      acc["fetch_#{fetch_type}_value"] = value_type
+      acc["fetch_#{fetch_type}_details"] = value_type
+    end.freeze
+
+    # The literal default_value node types we render. A non-literal default (a
+    # variable, method call, array/hash) renders to nil — recorded as "no observed
+    # literal default" rather than guessed.
+    LITERAL_NODES = [
+      Prism::StringNode, Prism::SymbolNode, Prism::IntegerNode,
+      Prism::FloatNode, Prism::TrueNode, Prism::FalseNode, Prism::NilNode
+    ].freeze
+
+    # One detected OpenFeature flag-evaluation call site. +flag_key+ is nil when the
+    # key is not a string/symbol literal (a *dynamic* reference: counted by the
+    # report, never catalogued, since a static scan cannot resolve it).
+    CallSite = Struct.new(:flag_key, :value_type, :default_value, :method_name, :path, :line)
+
+    module_function
+
+    # @param path [String] file to read
+    # @param rel_path [String] root-relative path stamped onto each call site
+    # @return [Array<CallSite>]
+    def scan_file(path, rel_path)
+      scan_source(File.read(path), rel_path)
+    end
+
+    # @param source [String] Ruby source
+    # @param path [String] path stamped onto each call site
+    # @return [Array<CallSite>]
+    def scan_source(source, path)
+      result = Prism.parse(source)
+      visitor = Visitor.new(path)
+      result.value.accept(visitor)
+      visitor.call_sites
+    end
+
+    # Walks the AST collecting OpenFeature flag-evaluation calls. No namespace
+    # tracking is needed: line→enclosing-method attribution is the orchestration's
+    # job (a {Flags::MethodIndex}, reusing the Prism {Parser}), keyed on the line
+    # recorded here.
+    class Visitor < Prism::Visitor
+      attr_reader :call_sites
+
+      def initialize(path)
+        @path = path
+        @call_sites = []
+        super()
+      end
+
+      def visit_call_node(node)
+        capture(node)
+        super
+      end
+
+      private
+
+      def capture(node)
+        value_type = METHOD_VALUE_TYPES[node.name.to_s]
+        return unless value_type
+
+        kwargs = keyword_arguments(node)
+        return unless kwargs.key?("flag_key")
+
+        @call_sites << CallSite.new(
+          literal_key(kwargs["flag_key"]),
+          value_type,
+          literal_default(kwargs["default_value"]),
+          node.name.to_s,
+          @path,
+          node.location.start_line
+        )
+      end
+
+      # Map of keyword name (String) => value node, for the trailing keyword hash.
+      def keyword_arguments(node)
+        args = node.arguments&.arguments || []
+        hash = args.find { |a| a.is_a?(Prism::KeywordHashNode) || a.is_a?(Prism::HashNode) }
+        return {} unless hash
+
+        hash.elements.each_with_object({}) do |assoc, acc|
+          next unless assoc.is_a?(Prism::AssocNode)
+          key = assoc.key
+          acc[key.unescaped] = assoc.value if key.is_a?(Prism::SymbolNode)
+        end
+      end
+
+      # The flag key when it is a string/symbol literal; nil otherwise (dynamic).
+      def literal_key(node)
+        case node
+        when Prism::StringNode, Prism::SymbolNode then node.unescaped
+        end
+      end
+
+      # A string rendering of a literal default value, or nil when not a literal.
+      def literal_default(node)
+        return nil unless node && LITERAL_NODES.any? { |k| node.is_a?(k) }
+
+        case node
+        when Prism::StringNode then node.unescaped
+        when Prism::SymbolNode then ":#{node.unescaped}"
+        else node.slice
+        end
+      end
+    end
+  end
+end

data/lib/moult/flags/classification.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Moult
+  module Flags
+    # The per-finding model for feature flags — this slice's realisation of Moult's
+    # protected per-finding API. Like a packwerk boundary violation (see
+    # {Boundaries::Severity}), a flag *reference* is a recorded FACT, not a
+    # probabilistic candidate: the scanner saw the call site. So we never manufacture
+    # a fake confidence (the finding's +confidence+ is null); the per-finding signal
+    # is a categorical CLASSIFICATION instead — the flag's value_type, how many times
+    # it is referenced, and the literal default value(s) observed.
+    #
+    # The genuinely confidence-graded judgement — *staleness* (is this flag dead /
+    # obsolete?) — needs a live OpenFeature provider to know which keys still exist,
+    # and is deferred (like the Coverband/Flipper live stores). So the humility
+    # invariant holds in this register too: a static scan can never prove a flag is
+    # unused (it may be referenced dynamically, via provider config, or from outside
+    # the codebase), and nothing here says it is.
+    #
+    # {classify} is a pure function of the observed signals — no IO, no Prism nodes —
+    # so it is pinned against hand-built inputs exactly like {ABC}, the coverage
+    # {Resolver}, the duplication {Confidence} model, and {Boundaries::Severity}.
+    # Drift is a bug.
+    module Classification
+      CATEGORY = "feature_flag"
+
+      # The value-type classification. boolean/string/number/object are read from the
+      # fetch_<type>_* method; +unknown+ is reserved for a flag referenced with more
+      # than one type (an ambiguity we record rather than resolve).
+      VALUE_TYPES = %w[boolean string number object unknown].freeze
+      MIXED = "unknown"
+
+      # One auditable note behind a classification. Mirrors the shared rule/detail
+      # reason shape; a classification is categorical (not a delta-sum) so it carries
+      # no +delta+, like {Boundaries::Severity::Reason}. Kept local so the flags slice
+      # does not couple to the dead-code/duplication Reason structs.
+      Reason = Struct.new(:rule, :detail) do
+        def to_h
+          {rule: rule.to_s, detail: detail}
+        end
+      end
+
+      # The classified result: the resolved value_type, the reference count, the
+      # distinct literal defaults, and the reasons behind them.
+      Assessment = Struct.new(:value_type, :reference_count, :default_values, :reasons)
+
+      module_function
+
+      # @param value_types [Array<String>] one observed value_type per call site
+      # @param default_values [Array<String, nil>] one observed literal default per
+      #   call site (nil where the default was not a literal)
+      # @return [Assessment]
+      def classify(value_types:, default_values:)
+        observed = value_types.uniq.sort
+        value_type = (observed.size == 1) ? observed.first : MIXED
+        reference_count = value_types.size
+        defaults = default_values.compact.uniq.sort
+
+        reasons = [type_reason(value_type, observed, reference_count)]
+        reasons << Reason.new(rule: :reference_count, detail: "referenced at #{pluralize(reference_count, "call site")}")
+        reasons << Reason.new(rule: :default_values, detail: "observed default value(s): #{defaults.join(", ")}") unless defaults.empty?
+
+        Assessment.new(value_type: value_type, reference_count: reference_count, default_values: defaults, reasons: reasons)
+      end
+
+      def type_reason(value_type, observed, reference_count)
+        if value_type == MIXED
+          Reason.new(rule: :mixed_value_types, detail: "referenced with differing value types (#{observed.join(", ")}); the flag type is ambiguous")
+        else
+          Reason.new(rule: :"#{value_type}_flag", detail: "evaluated as a #{value_type} flag across #{pluralize(reference_count, "reference")}")
+        end
+      end
+
+      def pluralize(count, noun)
+        "#{count} #{noun}#{"s" unless count == 1}"
+      end
+    end
+  end
+end

data/lib/moult/flags/snapshot.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Moult
+  module Flags
+    # Ingests a LOCAL OpenFeature provider flag-state export and normalises it into
+    # one Moult-owned value object ({FlagSet}) the {Staleness} model can read. This is
+    # the flags analogue of {Coverage} (which ingests a SimpleCov/stdlib dump) and of
+    # {Boundaries::Packwerk} (which ingests packwerk's committed artifacts): an
+    # external format comes in, only Moult types go out, so the provider is swappable
+    # and nothing downstream depends on its on-disk shape.
+    #
+    # One on-disk format is understood today (auto-detected, or forced via +format:+):
+    #
+    # * +:flagd+ — a flagd flag-definition JSON, the OpenFeature-native provider-
+    #   agnostic representation of flag state:
+    #   <tt>{"flags" => {key => {"state" => "ENABLED"|"DISABLED", "variants" => {...},
+    #   "defaultVariant" => "...", "targeting" => {...}, "metadata" => {...}}},
+    #   "metadata" => {...}}</tt>.
+    #
+    # flagd quirks normalised HERE and nowhere else (the swap point for a future
+    # provider/standard):
+    #
+    # * +state+ "ENABLED"/"DISABLED" maps to +enabled+ true/false.
+    # * A non-empty +targeting+ object means the flag serves more than the default
+    #   variant; an empty/absent one means it is fully rolled out to one variant.
+    # * flagd has no native archival/lifecycle state, so it is read from the standard
+    #   per-flag +metadata+ extension point: +metadata.archived == true+, or
+    #   +metadata.lifecycle+ in {"archived", "deprecated"}.
+    # * Timestamps (+metadata.updatedAt+/+lastModified+ per flag; the flag-set
+    #   +metadata+ export stamp) are captured as evidence only; the live, streaming
+    #   provider connection that would make them authoritative is deferred, exactly
+    #   like the live Coverband store.
+    #
+    # This adapter takes NO dependency on the +openfeature-sdk+ or any vendor SDK; it
+    # reads the export with stdlib JSON, mirroring how {Coverage} needs no simplecov
+    # and {Boundaries::Packwerk} no packwerk gem.
+    module Snapshot
+      module_function
+
+      # Provenance of a merged provider snapshot. Captured into the protected
+      # contract (analysis.provider) so a consumer can see where the staleness
+      # evidence came from. +exported_at+ also seeds the deferred time-decay slice.
+      Source = Struct.new(:backend, :version, :exported_at) do
+        def to_h
+          {backend: backend, version: version, exported_at: exported_at}
+        end
+      end
+
+      # The provider's normalised state for one flag key. +enabled+/+archived+/
+      # +has_targeting+ are the facts {Staleness} judges; +default_variant+ and
+      # +updated_at+ are captured for context and the deferred time-decay seed.
+      FlagState = Struct.new(:key, :enabled, :archived, :has_targeting, :default_variant, :updated_at)
+
+      # A normalised snapshot: the provider's state per flag key, plus provenance.
+      FlagSet = Struct.new(:states, :source) do
+        # @return [Boolean] whether the provider knows this key
+        def key?(flag_key)
+          states.key?(flag_key)
+        end
+
+        # @return [FlagState, nil] the provider's state for the key, or nil if absent
+        def state_for(flag_key)
+          states[flag_key]
+        end
+      end
+
+      ARCHIVED_LIFECYCLES = %w[archived deprecated].freeze
+
+      # @param path [String] path to the provider snapshot file
+      # @param format [Symbol] :auto (default) or :flagd
+      # @return [FlagSet]
+      def load(path, format: :auto)
+        raw = JSON.parse(File.read(path))
+        fmt = (format == :auto) ? detect_format(raw) : format
+        case fmt
+        when :flagd then from_flagd(raw, path)
+        else raise Moult::Error, "unknown provider snapshot format: #{fmt}"
+        end
+      rescue JSON::ParserError => e
+        raise Moult::Error, "could not parse provider snapshot #{path}: #{e.message}"
+      rescue Errno::ENOENT
+        raise Moult::Error, "no such provider snapshot: #{path}"
+      end
+
+      # A flagd export is a JSON object with a top-level "flags" map whose every
+      # entry carries a "state" — the unambiguous discriminator.
+      def detect_format(raw)
+        raise Moult::Error, "provider snapshot is not a JSON object" unless raw.is_a?(Hash)
+        flags = raw["flags"]
+        if flags.is_a?(Hash) && flags.values.all? { |f| f.is_a?(Hash) && f.key?("state") }
+          :flagd
+        else
+          raise Moult::Error, "could not auto-detect provider snapshot format; pass --provider-format flagd"
+        end
+      end
+
+      # @return [FlagSet]
+      def from_flagd(raw, path)
+        flags = raw["flags"].is_a?(Hash) ? raw["flags"] : {}
+        meta = raw["metadata"].is_a?(Hash) ? raw["metadata"] : {}
+        states = flags.each_with_object({}) do |(key, defn), acc|
+          acc[key] = flag_state(key, defn)
+        end
+        source = Source.new(
+          backend: "flagd",
+          version: stringify(meta["version"]),
+          exported_at: snapshot_timestamp(meta, path)
+        )
+        FlagSet.new(states: states, source: source)
+      end
+
+      def flag_state(key, defn)
+        defn = {} unless defn.is_a?(Hash)
+        meta = defn["metadata"].is_a?(Hash) ? defn["metadata"] : {}
+        FlagState.new(
+          key: key,
+          enabled: enabled?(defn["state"]),
+          archived: archived?(meta),
+          has_targeting: targeting?(defn["targeting"]),
+          default_variant: defn["defaultVariant"],
+          updated_at: stringify(meta["updatedAt"] || meta["lastModified"])
+        )
+      end
+
+      # ENABLED/DISABLED -> true/false; any other (or missing) state -> nil, which
+      # {Staleness} treats as neither rolled-out nor disabled (it falls through to
+      # active rather than inventing a verdict).
+      def enabled?(state)
+        case state.to_s.upcase
+        when "ENABLED" then true
+        when "DISABLED" then false
+        end
+      end
+
+      def archived?(meta)
+        return true if meta["archived"] == true
+        ARCHIVED_LIFECYCLES.include?(meta["lifecycle"].to_s.downcase)
+      end
+
+      def targeting?(targeting)
+        targeting.is_a?(Hash) && !targeting.empty?
+      end
+
+      # Best-effort export stamp: an explicit flag-set metadata timestamp if present,
+      # else the file mtime (noted only as a fallback; it seeds deferred time-decay).
+      def snapshot_timestamp(meta, path)
+        stamp = meta["exportedAt"] || meta["exported_at"] || meta["updatedAt"]
+        return stringify(stamp) if stamp
+        File.mtime(path).utc.iso8601
+      rescue
+        nil
+      end
+
+      def stringify(value)
+        value&.to_s
+      end
+    end
+  end
+end