ecoportal-api-graphql 1.3.10 → 1.3.11

data/lib/ecoportal/api/graphql/diff/cross_object_diff.rb

@@ -0,0 +1,165 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # Cross-object diff: two templates/pages that DO NOT share Mongo ids (UAT<->PROD,
+        # page<->template). Because nothing has the same id as its counterpart, we cannot match by id
+        # (that is `VersionDiff`). Instead we PAIR the fields as an equivalence problem
+        # (`Pairing::Engine` — genome + type + label + options, human-assisted, ledger-backed), build
+        # an id-correspondence map from the accepted pairs, then emit the SAME `Change` output against
+        # that map so the existing `CommandSynthesizer` / `Deploy` layer can consume it unchanged.
+        #
+        # This deliberately operates at the FIELD level — the load-bearing simplifying principle
+        # (domain ref §6): sections/stages are scaffolding, customer data lives in the data-fields, so
+        # a cross-object diff pairs FIELDS precisely and treats structure as context. Structure-level
+        # (stage/section) reconciliation across id-spaces is not attempted here (no reliable pairing
+        # signal for scaffolding) — it is left to the human review the engine already routes to.
+        #
+        #   engine = Pairing::Engine.new(ledger: ledger)          # optional
+        #   diff   = CrossObjectDiff.new(uat_doc, prod_doc, engine: engine,
+        #                                strategy: Strategy.new(pairing: :assisted, scope: :data_migration))
+        #   diff.changes    # => [Change, ...]  (field label/type changes on paired fields; +added/-removed)
+        #   diff.pairing    # => Pairing::Engine::Result (accepted / ambiguous / unmatched — for review)
+        #   diff.unresolved # => [field-doc, ...] sources the human must adjudicate (ambiguous+unmatched)
+        #
+        # SAFETY — only ACCEPTED pairs are treated as equivalences; ambiguous/unmatched sources are
+        # surfaced in `unresolved` and NEVER auto-paired or auto-removed. A same-label field whose
+        # genome contradicts is escalated, not silently matched (the engine guarantees this).
+        class CrossObjectDiff
+          attr_reader :strategy
+
+          # @param source_doc [Hash] the "before" template/page (e.g. the desired/UAT state).
+          # @param target_doc [Hash] the "after"/destination template/page (e.g. PROD).
+          # @param engine   [Pairing::Engine,nil] the equivalence matcher; a default one is built when
+          #   nil. Provide one wired to a `Ledger` to reuse confirmed pairings and learn over time.
+          # @param strategy [Strategy] scope + move-sensitivity. Pairing is inherently cross-object
+          #   here; `strategy.pairing` is informational (which signal set the caller intends).
+          def initialize(source_doc, target_doc, engine: nil, strategy: Strategy.new(pairing: :assisted))
+            @source   = source_doc || {}
+            @target   = target_doc || {}
+            @engine   = engine || Pairing::Engine.new
+            @strategy = strategy || Strategy.new(pairing: :assisted)
+          end
+
+          # The `Pairing::Engine::Result` for the field sets (accepted / ambiguous / unmatched).
+          def pairing
+            @pairing ||= @engine.pair(source_fields, target_fields)
+          end
+
+          # Source field docs the engine could not confidently pair — the human review set. These are
+          # NOT emitted as removals (we do not know they were deleted vs merely unpaired).
+          def unresolved
+            pairing.ambiguous.map(&:source) + pairing.unmatched
+          end
+
+          # Strategy-filtered change-set, emitted against the pairing map (target ids translated into
+          # the source id-space so the changes replay coherently through the synthesizer).
+          def changes
+            @changes ||= @strategy.filter(all_changes)
+          end
+
+          def changelog
+            changes.map(&:description)
+          end
+
+          def summary
+            by_op = changes.group_by(&:op)
+            {
+              added:      by_op.fetch(:added, []).size,
+              removed:    by_op.fetch(:removed, []).size,
+              changed:    by_op.fetch(:changed, []).size,
+              moved:      by_op.fetch(:moved, []).size,
+              total:      changes.size,
+              paired:     pairing.accepted.size,
+              unresolved: unresolved.size
+            }
+          end
+
+          def to_h
+            { summary: summary, changes: changes.map(&:to_h), pairing: pairing.to_h }
+          end
+
+          private
+
+          # Emit field-level changes off the pairing:
+          #   * accepted pair (src<->tgt): compare label/type/config; the change id is the SOURCE
+          #     field id (the id-space the synthesizer/target-resolver expects to translate);
+          #   * source with no accepted target: :removed (only from the confidently-paired frame —
+          #     unresolved sources are held back for review, never auto-removed);
+          #   * target with no accepted source: :added.
+          def all_changes
+            accepted   = pairing.accepted
+            paired_src = accepted.map(&:source_id)
+            paired_tgt = accepted.map(&:target_id)
+
+            compared = accepted.flat_map { |c| compare_pair(c) }
+            removed  = removed_changes(paired_src)
+            added    = added_changes(paired_tgt)
+
+            compared + removed + added
+          end
+
+          def compare_pair(candidate)
+            src = candidate.source
+            tgt = candidate.target
+            id  = candidate.source_id
+            cmp = []
+            cmp << field_change(id, src, tgt, 'label', src['label'], tgt['label']) if src['label'] != tgt['label']
+            cmp << field_change(id, src, tgt, 'type', field_type(src), field_type(tgt)) if field_type(src) != field_type(tgt)
+            cmp
+          end
+
+          # Source fields with no accepted counterpart AND that were confidently classified (i.e. not
+          # sitting in the unresolved review set) → removed. A source in `unresolved` is never emitted
+          # as a removal.
+          def removed_changes(paired_src)
+            held = unresolved.map { |f| f['id'] }
+            source_fields.reject { |f| paired_src.include?(f['id']) || held.include?(f['id']) }.map do |f|
+              Change.new(op: :removed, kind: :field, id: f['id'], label: f['label'])
+            end
+          end
+
+          # Target fields with no accepted counterpart → added, EXCEPT those tangled in an ambiguous
+          # candidate (a target the engine proposed but did not confirm): those are held for review,
+          # never auto-added (they may be the same field as an unresolved source, relabelled).
+          def added_changes(paired_tgt)
+            held = pairing.ambiguous.map(&:target_id)
+            target_fields.reject { |f| paired_tgt.include?(f['id']) || held.include?(f['id']) }.map do |f|
+              Change.new(op: :added, kind: :field, id: f['id'], label: f['label'])
+            end
+          end
+
+          def field_change(id, _src, tgt, attribute, before, after) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :changed, kind: :field, id: id, label: tgt['label'],
+                       attribute: attribute, before: before, after: after)
+          end
+
+          def field_type(field)
+            field['__typename'] || field['type']
+          end
+
+          def source_fields
+            @source_fields ||= fields_of(@source)
+          end
+
+          def target_fields
+            @target_fields ||= fields_of(@target)
+          end
+
+          # Flatten every data-field doc out of a page/template doc (stages -> sections -> fields).
+          def fields_of(doc)
+            out = []
+            Array(doc['stages']).each do |st|
+              Array(st['sections']).each do |sec|
+                out.concat(Array(sec['dataFields']))
+                out.concat(Array(sec['leftDataFields']))
+                out.concat(Array(sec['rightDataFields']))
+              end
+            end
+            out.select { |f| f.is_a?(Hash) && f['id'] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/diff/deploy.rb

@@ -0,0 +1,121 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # Deploy orchestration: turns a diff into the replayable, ordered WorkflowCommand batch that
+        # `executeWorkflowCommands` consumes — plus the honest list of changes that could NOT be
+        # synthesised (needs-human), so a review step can gate the apply.
+        #
+        # Two entry points:
+        #
+        #   # self-version replay (same object, real ids) — the "commit" replayed onto itself/a clone
+        #   plan = Deploy.from_versions(before_doc, after_doc)
+        #
+        #   # cross-object deploy (UAT delta -> a real PROD target): the diff gives the delta, but the
+        #   # move targets (section/stage) must resolve against the PROD doc's ids.
+        #   plan = Deploy.from_versions(uat_v1, uat_v2, target_doc: prod_doc)
+        #
+        #   plan.commands       # => ordered Array of built command hashes, ready to send
+        #   plan.unsupported    # => [Change, ...] needing human handling (never guessed)
+        #   plan.changelog      # => human one-liners for a ticket / review checklist
+        #   plan.execute!(page) # => sends via the given executor (page.execute_workflow_commands)
+        #
+        # SAFETY — `Deploy` is inert until `execute!` is called with an explicit executor. It never
+        # applies anything on its own, and it surfaces `unsupported` so a human gates the deploy.
+        class Deploy
+          attr_reader :diff, :synthesizer
+
+          # @param diff     [VersionDiff]
+          # @param resolver [#resolve, nil] maps move targets (stage name / section heading) to ids.
+          # @param thread_placeholders [Boolean] thread client-chosen placeholderIds so that an
+          #   add-then-reference sequence (e.g. add a Select field, then add its options) stays
+          #   self-consistent within one executeWorkflowCommands call. ON by default for deploy —
+          #   the whole batch is applied to a target where the source ids are not valid.
+          def initialize(diff, resolver: nil, thread_placeholders: true)
+            @diff        = diff
+            @synthesizer = CommandSynthesizer.new(
+              diff.changes, resolver: resolver, thread_placeholders: thread_placeholders
+            )
+          end
+
+          # Build a plan from two snapshots. When `target_doc` is given (cross-object deploy), a
+          # resolver is derived from it so field/section moves can address the target's real ids.
+          # An explicit `resolver:` overrides the derived one.
+          #
+          # `strategy:` selects the diff modality (scope / move-sensitivity / intent). It defaults to
+          # the self-version structural changelog strategy — the historical behaviour. When the
+          # strategy's `intent` is `:deploy` (or unspecified) placeholder threading stays ON.
+          def self.from_versions(before_doc, after_doc, target_doc: nil, resolver: nil,
+                                 thread_placeholders: true, strategy: Strategy.default)
+            resolver ||= (IdResolver.from_doc(target_doc) if target_doc)
+            diff = VersionDiff.new(before_doc, after_doc, strategy: strategy)
+            new(diff, resolver: resolver, thread_placeholders: thread_placeholders)
+          end
+
+          # Build a plan for a CROSS-OBJECT deploy (UAT<->PROD, page<->template): the two docs do not
+          # share ids, so fields are PAIRED (equivalence) before the delta is emitted. The pairing
+          # (accepted/ambiguous/unmatched) is exposed via `#pairing` so a human can adjudicate the
+          # unresolved set before applying. `engine:` lets the caller pass a `Pairing::Engine` wired
+          # to a `Ledger` (learns over time); `strategy:` defaults to the assisted/data-migration mode.
+          #
+          #   plan = Deploy.from_cross_object(uat_doc, prod_doc, engine: engine)
+          #   plan.pairing.ambiguous   # review before deploy
+          #   plan.commands            # the paired delta as WorkflowCommands
+          def self.from_cross_object(source_doc, target_doc, engine: nil, resolver: nil,
+                                     thread_placeholders: true,
+                                     strategy: Strategy.new(pairing: :assisted, scope: :data_migration, intent: :deploy))
+            resolver ||= (IdResolver.from_doc(target_doc) if target_doc)
+            diff = CrossObjectDiff.new(source_doc, target_doc, engine: engine, strategy: strategy)
+            new(diff, resolver: resolver, thread_placeholders: thread_placeholders)
+          end
+
+          # The pairing result when this plan is cross-object (nil for a self-version plan). Lets a
+          # caller inspect/adjudicate ambiguous + unmatched pairings before `execute!`.
+          def pairing
+            @diff.respond_to?(:pairing) ? @diff.pairing : nil
+          end
+
+          # Ordered, dependency-safe Array of built command hashes ready for executeWorkflowCommands.
+          def commands
+            @synthesizer.commands
+          end
+
+          # Changes with no faithful command — surfaced for human review, never guessed.
+          def unsupported
+            @synthesizer.unsupported
+          end
+
+          def changelog
+            @diff.changelog
+          end
+
+          def summary
+            {
+              changes:     @diff.summary,
+              commands:    commands.size,
+              unsupported: unsupported.size
+            }
+          end
+
+          # True when every detected change was synthesised into a command (nothing needs a human).
+          def fully_supported?
+            unsupported.empty?
+          end
+
+          def to_h
+            { summary: summary, commands: commands, unsupported: unsupported.map(&:to_h) }
+          end
+
+          # Apply the batch. `executor` must respond to `execute_workflow_commands(commands)` (the
+          # gem's page/template mutation facade). Raises unless the plan is fully supported — the
+          # caller must review/clear `unsupported` first — unless `allow_partial: true`.
+          def execute!(executor, allow_partial: false)
+            raise ArgumentError, "#{unsupported.size} unsupported change(s); review before deploy" unless fully_supported? || allow_partial
+
+            executor.execute_workflow_commands(commands)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/diff/id_resolver.rb

@@ -0,0 +1,64 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # Resolves the human keys a `VersionDiff` records (stage NAME, section HEADING) into the
+        # target-doc ids that move commands need (moveField -> section id, add/removeStageSection ->
+        # stage id). A structural diff only knows those human keys; this fills the gap WITHOUT
+        # guessing — it looks them up in a real target doc (the deploy destination), so
+        # `CommandSynthesizer` can emit faithful move commands.
+        #
+        # Answers `resolve(kind, key) => id | nil`. A nil (ambiguous / not found) keeps the move
+        # UNSUPPORTED rather than picking a wrong id.
+        #
+        #   resolver = IdResolver.from_doc(prod_template_doc)
+        #   CommandSynthesizer.new(changes, resolver: resolver)
+        #
+        # AMBIGUITY — if two stages share a name (or two sections a heading), the key is ambiguous
+        # and resolves to nil (the caller must disambiguate). Uniqueness is the safe default.
+        class IdResolver
+          # Build from an explicit map: { stage: { 'Report' => 'stg1' }, section: { 'Location' => 'sec1' } }
+          def initialize(index = {})
+            @index = index
+          end
+
+          # Build a resolver by indexing a page/template doc's stages (by name) and sections
+          # (by heading). Duplicate keys are dropped (resolve -> nil) so we never pick arbitrarily.
+          def self.from_doc(doc)
+            doc ||= {}
+            stages   = {}
+            sections = {}
+            Array(doc['stages']).each do |st|
+              mark(stages, st['name'], st['id'])
+              Array(st['sections']).each { |sec| mark(sections, sec['heading'], sec['id']) }
+            end
+            new(stage: strip_ambiguous(stages), section: strip_ambiguous(sections))
+          end
+
+          # @return [String,nil] the target id for (kind, key), or nil if unknown/ambiguous.
+          def resolve(kind, key)
+            @index.dig(kind.to_sym, key)
+          end
+
+          class << self
+            private
+
+            def mark(bucket, key, id)
+              return if key.nil? || id.nil?
+
+              (bucket[key] ||= []) << id
+            end
+
+            # Keep only keys that map to exactly one id; ambiguous keys are omitted (resolve -> nil).
+            def strip_ambiguous(bucket)
+              bucket.each_with_object({}) do |(key, ids), out|
+                uniq = ids.uniq
+                out[key] = uniq.first if uniq.size == 1
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/diff/pairing/candidate.rb

@@ -0,0 +1,32 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        module Pairing
+          # A scored pairing proposal: source object (id-space A) <-> target object (id-space B),
+          # with the aggregate confidence and the per-signal breakdown that produced it.
+          #
+          # `source`/`target` are the raw field docs (Hashes) being paired. `score` is 0.0..1.0.
+          # `signals` maps signal-name => contribution (for transparency + the ledger + Product's
+          # Field-ID data). `matched_by` names the dominant signal (e.g. :genome, :label, :ledger).
+          Candidate = Struct.new(:source, :target, :score, :signals, :matched_by, keyword_init: true) do
+            def source_id
+              source && source['id']
+            end
+
+            def target_id
+              target && target['id']
+            end
+
+            def to_h
+              {
+                source_id: source_id, target_id: target_id, score: score,
+                matched_by: matched_by, signals: signals
+              }.compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/diff/pairing/engine.rb

@@ -0,0 +1,173 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        module Pairing
+          # The equivalence-matching engine for CROSS-OBJECT pairing (UAT<->PROD, page<->template).
+          #
+          # Given two lists of field docs living in different id-spaces, it proposes pairings by:
+          #   1. consulting the LEDGER first — a previously-confirmed pair auto-resolves (method
+          #      :ledger, confidence 1.0), so pairing improves over time and only novelty is scored;
+          #   2. otherwise scoring every remaining source×target candidate with multi-signal
+          #      confidence (genome + type + label + options — see Signals), picking the best target
+          #      per source in a stable, greedy, one-to-one assignment (highest scores first).
+          #
+          # It then CLASSIFIES each best candidate:
+          #   - `accepted`  — score >= accept_threshold: high confidence, auto-paired;
+          #   - `ambiguous` — accept > score >= review_threshold, OR the top two candidates are within
+          #                   `tie_margin` (genuinely close): route to a HUMAN to adjudicate;
+          #   - `unmatched` — no target scored >= review_threshold: escalate as a novelty.
+          #
+          # NEVER guesses: only `accepted` pairs are safe to auto-apply / auto-record; ambiguous and
+          # unmatched are surfaced for human resolution. Confirmed decisions are written back to the
+          # ledger by the caller (or via #confirm!) so the next run needs no human on them.
+          class Engine
+            DEFAULTS = { accept_threshold: 0.85, review_threshold: 0.5, tie_margin: 0.1 }.freeze
+
+            Result = Struct.new(:accepted, :ambiguous, :unmatched, keyword_init: true) do
+              # source field docs with no acceptable target — the pure novelty set.
+              def resolved?
+                ambiguous.empty? && unmatched.empty?
+              end
+
+              def to_h
+                {
+                  accepted:  accepted.map(&:to_h),
+                  ambiguous: ambiguous.map(&:to_h),
+                  unmatched: unmatched.map { |f| { source_id: f['id'], label: f['label'] } }
+                }
+              end
+            end
+
+            # @param ledger [Ledger,nil] consulted first + written to on #confirm!.
+            # @param kind   [Symbol] entity kind recorded in the ledger (default :field).
+            def initialize(ledger: nil, kind: :field, **thresholds)
+              @ledger = ledger
+              @kind   = kind
+              @cfg    = DEFAULTS.merge(thresholds)
+            end
+
+            # Pair `sources` (id-space A) to `targets` (id-space B). Returns a Result.
+            def pair(sources, targets)
+              sources = Array(sources)
+              targets = Array(targets)
+
+              accepted, remaining_sources, remaining_targets = apply_ledger(sources, targets)
+              scored = score_all(remaining_sources, remaining_targets)
+              assign(scored, remaining_sources, accepted)
+            end
+
+            # Persist a confirmed pairing to the ledger (auto-accept or human decision). No-op
+            # without a ledger. `matched_by` overrides the candidate's dominant signal (e.g. :human
+            # when a person adjudicated). Returns the recorded Entry (or nil).
+            def confirm!(candidate, matched_by: nil)
+              return nil unless @ledger
+
+              @ledger.record(
+                kind: @kind, source_id: candidate.source_id, target_id: candidate.target_id,
+                matched_by: matched_by || candidate.matched_by, confidence: candidate.score,
+                signals: candidate.signals
+              )
+            end
+
+            private
+
+            # Pull out sources already confirmed in the ledger (auto-resolved), consuming the matched
+            # targets so they cannot be re-assigned. Returns [accepted, sources_left, targets_left].
+            def apply_ledger(sources, targets)
+              return [[], sources, targets] unless @ledger
+
+              by_id    = targets.each_with_object({}) { |t, h| h[t['id']] = t if t['id'] }
+              accepted = []
+              used     = []
+
+              left = sources.reject do |src|
+                tid = @ledger.target_for(@kind, src['id'])
+                tgt = tid && by_id[tid]
+                next false unless tgt
+
+                accepted << ledger_candidate(src, tgt)
+                used << tid
+                true
+              end
+
+              [accepted, left, targets.reject { |t| used.include?(t['id']) }]
+            end
+
+            def ledger_candidate(source, target)
+              Candidate.new(source: source, target: target, score: 1.0, matched_by: :ledger,
+                            signals: { ledger: 1.0 })
+            end
+
+            # Score every source×target pair; keep only those at/above the review threshold, best
+            # first, so the greedy assignment takes the strongest links first.
+            def score_all(sources, targets)
+              sources.flat_map do |src|
+                targets.map { |tgt| score_pair(src, tgt) }
+              end.select { |c| c.score >= @cfg[:review_threshold] }.sort_by { |c| -c.score }
+            end
+
+            def score_pair(source, target)
+              parts = {
+                genome:  Signals.genome(source, target),
+                type:    Signals.type(source, target),
+                label:   Signals.label(source, target),
+                options: Signals.options(source, target)
+              }
+              applied = parts.compact
+              score   = weighted_average(applied)
+              Candidate.new(source: source, target: target, score: score,
+                            signals: applied, matched_by: dominant(applied))
+            end
+
+            # Weighted mean over the signals that APPLIED (nil signals are excluded and their weight
+            # dropped), so a select field is not penalised for genome being absent, etc.
+            def weighted_average(applied)
+              return 0.0 if applied.empty?
+
+              num = applied.sum { |name, val| Signals::WEIGHTS.fetch(name, 0) * val }
+              den = applied.sum { |name, _| Signals::WEIGHTS.fetch(name, 0) }
+              den.zero? ? 0.0 : (num / den).round(4)
+            end
+
+            def dominant(applied)
+              return nil if applied.empty?
+
+              applied.max_by { |name, val| [val, Signals::WEIGHTS.fetch(name, 0)] }.first
+            end
+
+            # Greedy one-to-one assignment: walk best-scored candidates first, take a pair when both
+            # ends are still free. Then classify the taken pairs and collect unmatched sources.
+            def assign(scored, sources, accepted)
+              ambiguous   = []
+              taken_src   = accepted.map(&:source_id)
+              taken_tgt   = accepted.map(&:target_id)
+              best_by_src = scored.group_by(&:source_id)
+
+              scored.each do |cand|
+                next if taken_src.include?(cand.source_id) || taken_tgt.include?(cand.target_id)
+
+                bucket = accept?(cand, best_by_src[cand.source_id]) ? accepted : ambiguous
+                bucket << cand
+                taken_src << cand.source_id
+                taken_tgt << cand.target_id
+              end
+
+              unmatched = sources.reject { |s| taken_src.include?(s['id']) }
+              Result.new(accepted: accepted, ambiguous: ambiguous, unmatched: unmatched)
+            end
+
+            # Accept only when confidently above threshold AND not in a near-tie with the runner-up
+            # for the same source (a close second means the human should decide).
+            def accept?(cand, siblings)
+              return false if cand.score < @cfg[:accept_threshold]
+
+              runner_up = Array(siblings).reject { |c| c.target_id == cand.target_id }.map(&:score).max
+              runner_up.nil? || (cand.score - runner_up) >= @cfg[:tie_margin]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/diff/pairing/ledger.rb

@@ -0,0 +1,119 @@
+require 'json'
+require 'time'
+
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        module Pairing
+          # The LEARNING LEDGER — a first-class artifact that records CONFIRMED equivalences between
+          # objects that live in different id-spaces (UAT<->PROD, page<->template). Because MongoDB
+          # gives every object a distinct id and nothing is shared across counterparts, pairing is an
+          # equivalence / entity-resolution problem, not a lookup. Every decision the engine (or a
+          # human) makes is persisted here so pairing IMPROVES over time: on the next run the ledger
+          # is consulted FIRST and previously-resolved pairs auto-resolve, leaving only genuine
+          # novelty for the human to adjudicate.
+          #
+          # An entry is keyed by (kind, source_id) and records the paired target_id plus HOW it was
+          # resolved (the method, the confidence, the signals, a timestamp). This log of *how* is the
+          # bridge data Product's Field-ID / template-entity-id effort needs.
+          #
+          #   ledger = Ledger.load('pairings.json')      # or Ledger.new (in-memory)
+          #   ledger.record(kind: :field, source_id: 'a', target_id: 'b',
+          #                 method: :genome, confidence: 0.98, signals: {...})
+          #   ledger.lookup(:field, 'a')   # => Entry or nil
+          #   ledger.save                  # persist back to the same path
+          #
+          # SAFETY — the ledger stores only decisions that were CONFIRMED (auto-accepted at high
+          # confidence, or human-adjudicated). Ambiguous/low-confidence candidates are never written;
+          # they are escalated. The ledger is thus a growing store of ground truth, never guesses.
+          class Ledger
+            Entry = Struct.new(:kind, :source_id, :target_id, :matched_by, :confidence, :signals,
+                               :recorded_at, keyword_init: true) do
+              def to_h
+                {
+                  kind: kind, source_id: source_id, target_id: target_id, matched_by: matched_by,
+                  confidence: confidence, signals: signals, recorded_at: recorded_at
+                }.compact
+              end
+            end
+
+            # @param entries [Array<Entry,Hash>] existing entries (e.g. from a loaded file).
+            # @param path    [String,nil] where #save writes; defaults to the load path.
+            def initialize(entries: [], path: nil)
+              @path    = path
+              @entries = {}
+              Array(entries).each { |e| add_entry(coerce(e)) }
+            end
+
+            # Load a ledger from a JSON file. A missing file yields an empty (still writable) ledger.
+            def self.load(path)
+              data = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+              new(entries: data['entries'] || [], path: path)
+            end
+
+            # Record a CONFIRMED equivalence. `matched_by` names how it was resolved (:genome,
+            # :label, :ledger, :human, ...). Later records for the same (kind, source_id) supersede
+            # earlier ones (a human can correct an auto-accept). Returns the stored Entry.
+            def record(kind:, source_id:, target_id:, matched_by:, confidence: nil, signals: nil)
+              entry = Entry.new(
+                kind: kind.to_sym, source_id: source_id, target_id: target_id,
+                matched_by: matched_by&.to_sym, confidence: confidence, signals: signals,
+                recorded_at: Time.now.utc.iso8601
+              )
+              add_entry(entry)
+              entry
+            end
+
+            # The confirmed Entry for (kind, source_id), or nil if never resolved.
+            def lookup(kind, source_id)
+              @entries[[kind.to_sym, source_id]]
+            end
+
+            # The confirmed target id for (kind, source_id), or nil.
+            def target_for(kind, source_id)
+              lookup(kind, source_id)&.target_id
+            end
+
+            def entries
+              @entries.values
+            end
+
+            def size
+              @entries.size
+            end
+
+            def to_h
+              { entries: entries.map(&:to_h) }
+            end
+
+            # Persist to `path` (or the load path). Returns the path written.
+            def save(path = @path)
+              raise ArgumentError, 'no path to save the ledger to' if path.nil?
+
+              File.write(path, JSON.pretty_generate(to_h))
+              path
+            end
+
+            private
+
+            def add_entry(entry)
+              @entries[[entry.kind, entry.source_id]] = entry
+            end
+
+            def coerce(entry)
+              return entry if entry.is_a?(Entry)
+
+              h = entry.transform_keys(&:to_sym)
+              Entry.new(
+                kind: h[:kind]&.to_sym, source_id: h[:source_id], target_id: h[:target_id],
+                matched_by: h[:matched_by]&.to_sym, confidence: h[:confidence], signals: h[:signals],
+                recorded_at: h[:recorded_at]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end