eco-helpers 3.2.14 → 3.2.23

data/lib/eco/api/usecases/graphql/compat/ooze_redirect.rb

@@ -0,0 +1,223 @@
+module Eco::API::UseCases::GraphQL::Compat
+  # Transparently redirects an OozeSamples-based use case from the APIv2 ooze
+  # path to the GraphQL compat layer.  Include it in the case class and nothing
+  # else needs to change in the script.
+  #
+  # ## What it redirects
+  #
+  # - Page iteration: `with_each_entry` fetches via `graphql.pages.get`
+  # - `api_v2` / `apiv2`: returns the graphql compat client
+  # - `stage(name)`: resolves via `target.stages[name]` (GraphQL stage model)
+  # - `with_fields(ooz, label:, type:)`: reads from `ooz.components` (GraphQL)
+  # - `update_ooze(ooz)`: saves via `graphql.pages.update`
+  # - `target.submit!` / `target.sign_off!`: captured and forwarded to `graphql.pages.update`
+  #
+  # ## What it patches (one-time, guarded)
+  #
+  # - V2 type classes (`PlainTextField`, `SelectionField`, etc.) recognise
+  #   GraphQL instances in `case/when` dispatch via `===`
+  # - GraphQL `People` field: `people_ids <<` triggers dirty tracking
+  # - GraphQL `CrossReference` field: `add`, `clear`, `reference_ids`
+  # - GraphQL `Select` field: `select`, `deselect`, `values`, `options`
+  #   (options returns Struct objects with `.name` / `.value`)
+  # - All GraphQL fields: `ooze` stub returns a minimal object for warning messages
+  # - `Interface::BasePage`: `submit!(stage_id:)` queues a submit-only flag (completes
+  #   the fill-in task); `sign_off!(stage_id:)` queues sign-off. Tasks are sequential
+  #   (fill-in → review): sign-off on a not-yet-submitted stage submits + signs off in
+  #   one go (completePageTask{ signOff: true }). `submit!(force: true)` maps to
+  #   completePageTask{ forcedComplete: true } (admin/superuser; skips the required-field check).
+  #
+  # ## Per-run debug logging
+  #
+  # Each type of redirection logs once per run (not per page) at `:debug` level.
+  # Filter with `ECOPORTAL_LOG_LEVEL=debug` or the session logger config.
+  #
+  # ## Usage
+  #
+  #   class Custom::UseCase::TOOCSCoding < Eco::API::UseCases::OozeSamples::TargetOozesUpdateCase
+  #     include Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  #     # ... rest of class unchanged ...
+  #   end
+  #
+  # ## Limitations
+  #
+  # - Force / binding operations (`target.forces`, `force.bindings`) are not
+  #   available in GraphQL — those calls will raise NoMethodError.
+  # - Field property setters (`fld.label=`, `fld.required=`) are template
+  #   mutations; they are not supported and will raise NoMethodError.
+  # - `page_result.membranes` (on PreviewPage search results) is not supported
+  #   directly; use register search via `graphql.registers.search` instead.
+  #
+  # ## TODO: Force / binding support (blocked on GraphQL endpoint)
+  #
+  # Engineering is working on exposing "legacy forces" via the GraphQL API.
+  # Once that endpoint is available, extend this module with a `ForceCompat`
+  # sub-module (same include pattern — nothing changes in end scripts) covering:
+  #
+  #   target.forces.get_by_name(name)      → query forces by name on a page
+  #   force.bindings.get_by_name(name)     → field bindings on a force
+  #   force.bindings.add(field, name:)     → add a binding
+  #   force.bindings.delete!(binding)      → remove a binding
+  #   force.custom_script                  → read the LISP script
+  #   force.custom_script = new_script     → write the LISP script
+  #   force.script                         → raw script content (alias)
+  #
+  # Affected cases currently blocked: roughly half of all ooze cases in the internal script repos'
+  # survey (per-customer breakdown kept in the internal migration notes, not in this gem).
+  #
+  # Implementation sketch (to be built when the endpoint lands):
+  #
+  #   module ForceCompat
+  #     # Patch GraphQL BasePage to respond to .forces
+  #     # Returns a proxy whose #get_by_name queries the GraphQL force endpoint
+  #     # and returns ForceProxy objects wrapping the response.
+  #     # ForceProxy exposes #bindings (BindingsProxy), #custom_script, #script.
+  #     # BindingsProxy exposes #get_by_name, #add, #delete!.
+  #   end
+  #
+  #   OozeRedirect.include(ForceCompat)  # or extend OozeRedirect::FieldPatches
+  module OozeRedirect
+    require_relative 'ooze_redirect/dirty_array'
+    require_relative 'ooze_redirect/field_patches'
+    require_relative 'ooze_redirect/force_compat'
+
+    def self.included(base)
+      FieldPatches.apply!
+      # Provide `graphql` (lazy, memoized session.api(version: :graphql)) regardless of
+      # the host's base class. OozeSamples cases (cans/toocs) don't include the GraphQL
+      # helpers that Custom::UseCase paths pick up, yet Infrastructure#api_v2 /
+      # #with_each_entry / #update_ooze all call `graphql` — without this they raise
+      # NameError: undefined `graphql`.
+      base.include(Eco::API::UseCases::GraphQL::Helpers::Base::GraphQLEnv)
+      # Prepend Infrastructure first so it sits below ForceCompat in the MRO.
+      # With Ruby's prepend, last-prepended wins — so ForceCompat::Infrastructure
+      # must be prepended AFTER Infrastructure to be first in the lookup chain:
+      #   MRO: ForceCompat::Infrastructure → Infrastructure → base class
+      base.prepend(Infrastructure)
+      base.prepend(ForceCompat::Infrastructure) if force_support?
+    end
+
+    # Returns true when the installed ecoportal-api-graphql gem exposes
+    # Query::PageWithForces (the forces-aware page query).
+    # Forces are NOT usable on GraphQL yet: Query::PageWithForces is a WIP whose query
+    # currently fails schema validation (selections on PageUnion; `id` on DataFieldBinding/
+    # SectionBinding; unused ForceFields) and the backend forces endpoint is still in
+    # progress. The class merely being *defined* is not a readiness signal — activating
+    # ForceCompat on that basis makes EVERY OozeRedirect case fetch via the broken force
+    # query (e.g. toocs, which doesn't even use forces). Keep OFF until forces actually
+    # work; then restore a real readiness check.
+    def self.force_support?
+      false
+    end
+
+    # Method overrides that replace the v2 infrastructure with GraphQL calls.
+    # Prepended onto the including class so they take priority over inherited methods.
+    module Infrastructure
+      # NOTE: with_each_entry / update_ooze / process_ooze are intentionally NOT overridden.
+      # The base OozeSamples loop (RegisterUpdateCase / TargetOozesUpdateCase) already does the
+      # right thing once api_v2 is redirected to GraphQL: it counts KPIs (search/retrieved/
+      # updated/created), dedups, queues, and — crucially — runs dry_run_feedback in simulate
+      # to PRINT the pending diff. Fetches go through ooze(id) → apiv2.pages.get (redirected
+      # below), and saves go through update_oozes → update_ooze → apiv2.pages.update. A captured
+      # target.submit!/sign_off! rides along on that single update via Input::Page::Update
+      # .from_model (it reads the page's _compat_* flags). Overriding the loop here is what
+      # silently dropped all of that — don't reintroduce it.
+
+      # --- API client redirect ------------------------------------------------
+
+      # Return the GraphQL compat client in place of the v2 client.
+      # Handles direct api_v2.pages.* calls in scripts that don't use OozeSamples
+      # iteration (e.g. get_new, create, update called directly).
+      def api_v2
+        warn_once(:api_v2, 'api_v2 → graphql compat layer')
+        graphql
+      end
+
+      alias apiv2 api_v2
+
+      # --- Stage access -------------------------------------------------------
+
+      # Resolve a stage by name from the current GraphQL page.
+      # Replaces the v2 stage fetch from OozeBaseCase.
+      def stage(id_name, ooze: target)
+        warn_once(:stage, "stage('#{id_name}') → StageView over target.stages[name]")
+        stg = ooze.stages[id_name.to_s]
+        return nil unless stg
+
+        # Return a StageView (v2 "page-at-a-stage" semantics): #id / #name / #state /
+        # #submit! / #as_update / #dirty? delegate to the PAGE, while #components and
+        # #sections are scoped to this stage. Scripts rely on stage.id == page.id
+        # (e.g. with_row(stage.id), keyed by page id); the raw Base::Page::Phased::Stage#id
+        # is the STAGE's own id and breaks that. Field objects stay the page's canonical
+        # ones, so mutations via stage.components still reach pages.update.
+        Ecoportal::API::GraphQL::Compat::StageView.new(ooze, stg.id)
+      rescue NoMethodError
+        log(:warn) { "[OozeRedirect] stages not available on #{ooze.class}" }
+        nil
+      end
+
+      # --- Field access -------------------------------------------------------
+
+      # Redirect field lookups from v2 component access to GraphQL components.
+      # Supports the same type: and label: keyword arguments.
+      def with_fields(ooz = target, type: nil, label: nil) # rubocop:disable Metrics/MethodLength
+        warn_once(:with_fields, 'with_fields → ooz.components (GraphQL)')
+        collection = ooz.respond_to?(:components) ? ooz.components : nil
+
+        unless collection
+          log(:warn) { "[OozeRedirect] No components on #{ooz.class}" }
+          return []
+        end
+
+        if label && type
+          field = collection.get_by_name(label)
+          field && type_match?(field, type) ? [field] : []
+        elsif label
+          [collection.get_by_name(label)].compact
+        elsif type
+          collection.get_by_type(type)
+        else
+          collection.to_a
+        end
+      end
+
+      # --- Dirty check --------------------------------------------------------
+
+      # v2 dirty?(ooze) reads patch_doc(ooze)['page']; the GraphQL compat get_body wraps the
+      # model's as_update under 'page' (nil when unchanged), so the base dirty? works too —
+      # but delegate to the model's real #dirty? for clarity AND treat a captured submit!/
+      # sign_off! as dirty, so the base update_ooze still fires for a page that only needs
+      # submitting (no field changes). The submit/sign-off itself is carried on that single
+      # update by Input::Page::Update.from_model (reads the _compat_* flags).
+      def dirty?(object)
+        return false unless object
+
+        pending = (object.respond_to?(:_compat_submit?)   && object._compat_submit?) ||
+                  (object.respond_to?(:_compat_sign_off?) && object._compat_sign_off?)
+        return true if pending
+        return object.dirty? if object.respond_to?(:dirty?)
+
+        super
+      end
+
+      private
+
+      # Log a debug message exactly once per use-case run per operation type.
+      def warn_once(op_key, message)
+        @_warned_ops ||= Set.new
+        return if @_warned_ops.include?(op_key)
+
+        @_warned_ops << op_key
+        log(:debug) { "[OozeRedirect] #{message}" }
+      end
+
+      # Check whether a GraphQL field matches a v2-style type string.
+      # v2 uses e.g. "select", "people", "cross_reference"; normalise both sides.
+      def type_match?(field, type_key)
+        target_norm = type_key.to_s.downcase.delete('_')
+        field_norm  = field.type.to_s.downcase.delete('_')
+        target_norm == field_norm
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/compat/parity/comparison.rb

@@ -0,0 +1,70 @@
+module Eco::API::UseCases::GraphQL::Compat
+  module Parity
+    # The result of comparing a legacy RunResult (A) against a native RunResult (B).
+    #
+    # Pure value object: given two RunResults it computes the KPI deltas, the set of
+    # page ids only one side touched, and the per-page payload diffs. `equivalent?`
+    # is the go/no-go signal the migration flips a case name on.
+    class Comparison
+      attr_reader :a, :b
+
+      def initialize(run_a, run_b)
+        @a = run_a
+        @b = run_b
+      end
+
+      # True when the two runs are indistinguishable on the canonical KPI set and on
+      # every per-page update payload.
+      def equivalent?
+        kpi_diff.empty? && only_in_a.empty? && only_in_b.empty? && payload_diffs.empty?
+      end
+
+      # Canonical KPI names whose values differ, => [a_value, b_value].
+      def kpi_diff
+        keys = a.kpis.keys | b.kpis.keys
+        keys.each_with_object({}) do |key, out|
+          av = a.kpis[key].to_i
+          bv = b.kpis[key].to_i
+          out[key] = [av, bv] if av != bv
+        end
+      end
+
+      # Page ids only the legacy run acted on.
+      def only_in_a
+        a.page_ids - b.page_ids
+      end
+
+      # Page ids only the native run acted on.
+      def only_in_b
+        b.page_ids - a.page_ids
+      end
+
+      # Per-page payload diffs for the ids BOTH runs touched, => [a_payload, b_payload].
+      def payload_diffs
+        (a.page_ids & b.page_ids).each_with_object({}) do |id, out|
+          ap = a.updates[id]
+          bp = b.updates[id]
+          out[id] = [ap, bp] if ap != bp
+        end
+      end
+
+      # Human-readable report of the divergences (empty when equivalent).
+      def report # rubocop:disable Metrics/AbcSize
+        return "PARITY OK — #{a.label} ≡ #{b.label}" if equivalent?
+
+        lines = ["PARITY MISMATCH — #{a.label} vs #{b.label}:"]
+        kpi_diff.each do |key, (av, bv)|
+          lines << "  * KPI #{key}: #{a.label}=#{av} #{b.label}=#{bv}"
+        end
+        lines << "  * only in #{a.label}: #{only_in_a.join(', ')}" unless only_in_a.empty?
+        lines << "  * only in #{b.label}: #{only_in_b.join(', ')}" unless only_in_b.empty?
+        payload_diffs.each do |id, (ap, bp)|
+          lines << "  * payload #{id}:"
+          lines << "      #{a.label}: #{ap.inspect}"
+          lines << "      #{b.label}: #{bp.inspect}"
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/compat/parity/harness.rb

@@ -0,0 +1,102 @@
+module Eco::API::UseCases::GraphQL::Compat
+  module Parity
+    # A/B parity harness for the ooze -> native GraphQL strangler-fig migration.
+    #
+    # Runs the SAME logical register-processing case through the two code paths —
+    # A: legacy (v2 / OozeRedirect shim), B: native GraphQL — and asserts that the
+    # observable outcome (KPI counters + per-page update payloads) is equivalent.
+    #
+    # The comparison logic (RunResult / Comparison) is PURE and offline-runnable.
+    # The harness itself is a thin orchestrator: you hand it two callables, each of
+    # which runs its side and returns a RunResult. In a live run each callable would
+    # execute the case in `-simulate` mode against the same test org, using a
+    # Recorder to capture what each side WOULD write (no data is mutated). Wiring the
+    # two live runs needs credentials + a test org; the structural machinery here is
+    # verified offline.
+    #
+    # == Usage (live)
+    #
+    #   harness = Parity::Harness.new(
+    #     legacy: -> { Parity::Harness.record('legacy') { |rec| run_legacy_case(rec) } },
+    #     native: -> { Parity::Harness.record('native') { |rec| run_native_case(rec) } }
+    #   )
+    #   comparison = harness.run
+    #   raise comparison.report unless comparison.equivalent?
+    #
+    # == Usage (offline / spec)
+    #
+    #   a = Parity::RunResult.new(label: 'legacy', kpis: {...}, updates: {...})
+    #   b = Parity::RunResult.new(label: 'native', kpis: {...}, updates: {...})
+    #   Parity::Harness.new(legacy: -> { a }, native: -> { b }).run.equivalent?
+    class Harness
+      # @param legacy [#call] returns the legacy-path RunResult.
+      # @param native [#call] returns the native-path RunResult.
+      def initialize(legacy:, native:)
+        @legacy = legacy
+        @native = native
+      end
+
+      # Execute both sides and compare. Returns a Parity::Comparison.
+      def run
+        a = @legacy.call
+        b = @native.call
+        assert_run_result!(a, 'legacy')
+        assert_run_result!(b, 'native')
+        a.compare_to(b)
+      end
+
+      # Capture the observable outcome of a case run into a RunResult.
+      #
+      # Yields a Recorder. The caller runs the case, feeding each page's would-be
+      # update payload to `recorder.record_update(page_id, payload)` (typically wired
+      # by stubbing the case's `update_page` to call `graphql.pages.get_body(page)`
+      # instead of persisting). After the run, pass the case's KPI hash to
+      # `recorder.kpis = case.kpis_hash` (or set counters individually).
+      #
+      # @param label [String] 'legacy' or 'native'.
+      # @yieldparam recorder [Recorder]
+      # @return [RunResult]
+      def self.record(label)
+        recorder = Recorder.new(label)
+        yield(recorder) if block_given?
+        recorder.to_run_result
+      end
+
+      private
+
+      def assert_run_result!(obj, side)
+        return if obj.is_a?(RunResult)
+
+        raise TypeError, "The #{side} callable must return a Parity::RunResult, got #{obj.class}"
+      end
+
+      # Collects a run's KPIs + per-page update payloads, then bakes a RunResult.
+      class Recorder
+        attr_accessor :kpis
+
+        def initialize(label)
+          @label   = label
+          @kpis    = {}
+          @updates = {}
+        end
+
+        # Record what a run WOULD send for `page_id`. Later ids for the same page
+        # overwrite (the last state wins — matching a real save of the final page).
+        def record_update(page_id, payload)
+          @updates[page_id.to_s] = payload
+          self
+        end
+
+        # Set a single canonical/native KPI counter by name.
+        def kpi(name, value)
+          @kpis[name.to_sym] = value
+          self
+        end
+
+        def to_run_result
+          RunResult.new(label: @label, kpis: @kpis, updates: @updates)
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/compat/parity/run_result.rb

@@ -0,0 +1,96 @@
+module Eco::API::UseCases::GraphQL::Compat
+  module Parity
+    # A normalised, comparable snapshot of ONE use-case run.
+    #
+    # The A/B parity harness reduces a run — whether it went through the legacy
+    # (v2 / OozeRedirect) path or the native GraphQL path — to just its OBSERVABLE
+    # outcome:
+    #   * `kpis`    — the KPI counter hash (search/retrieved/updated/created/… )
+    #   * `updates` — the per-page update payload the run WOULD send, keyed by page id
+    #
+    # Two runs are "equivalent" when, after normalisation, both are identical. This
+    # is the unit the strangler-fig migration is gated on: flip a case name only once
+    # its native RunResult matches the legacy RunResult over the same input.
+    #
+    # Everything here is PURE (no session, no network) so equivalence can be asserted
+    # offline in specs; the live capture step (feeding real runs in) is the only part
+    # that needs credentials.
+    class RunResult
+      attr_reader :label, :kpis, :updates
+
+      # @param label   [String] human tag for this side ('legacy' / 'native').
+      # @param kpis     [Hash] KPI counters. Keys are symbolised; values coerced to Integer.
+      # @param updates  [Hash{String=>Object}] page_id => update payload (any Hash-ish).
+      def initialize(label:, kpis: {}, updates: {})
+        @label   = label.to_s
+        @kpis    = normalize_kpis(kpis)
+        @updates = normalize_updates(updates)
+      end
+
+      # The set of page ids this run acted on.
+      def page_ids
+        updates.keys
+      end
+
+      # Compare against another RunResult, returning a Comparison value object.
+      def compare_to(other)
+        Comparison.new(self, other)
+      end
+
+      # Convenience: are the two runs equivalent?
+      def equivalent_to?(other)
+        compare_to(other).equivalent?
+      end
+
+      # Merge/normalise into a plain hash (handy for golden-file capture).
+      def to_h
+        { label: label, kpis: kpis, updates: updates }
+      end
+
+      # KPI names differ between the legacy and native cases (e.g. `updated_oozes`
+      # vs `updated_pages`). We compare on a CANONICAL subset of counters that both
+      # sides expose the same way, mapping each side's names onto the canon.
+      CANON_KPI_ALIASES = {
+        search:     %i[total_search_oozes total_search_pages search],
+        duplicated: %i[dupped_search_oozes dupped_search_pages duplicated],
+        retrieved:  %i[retrieved_oozes retrieved_pages retrieved],
+        updated:    %i[updated_oozes updated_pages updated],
+        created:    %i[created_oozes created_pages created],
+        skipped:    %i[skipped_pages skipped],
+        failed:     %i[failed_update_oozes failed_pages failed]
+      }.freeze
+
+      private
+
+      def normalize_kpis(raw)
+        source = raw.each_with_object({}) do |(k, v), out|
+          out[k.to_sym] = v
+        end
+
+        CANON_KPI_ALIASES.each_with_object({}) do |(canon, aliases), out|
+          key = aliases.find {|a| source.key?(a)}
+          out[canon] = key ? source[key].to_i : 0
+        end
+      end
+
+      # Normalise each update payload so a superficial key-order / string-vs-symbol
+      # difference between the two paths does not read as a real divergence.
+      def normalize_updates(raw)
+        raw.each_with_object({}) do |(id, payload), out|
+          out[id.to_s] = deep_normalize(payload)
+        end
+      end
+
+      def deep_normalize(value)
+        case value
+        when Hash
+          value.map {|k, v| [k.to_s, deep_normalize(v)]}.sort_by(&:first).to_h
+        when Array
+          value.map {|v| deep_normalize(v)}
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/compat.rb

@@ -0,0 +1,11 @@
+module Eco::API::UseCases::GraphQL
+  module Compat
+    module Parity
+    end
+  end
+end
+
+require_relative 'compat/ooze_redirect'
+require_relative 'compat/parity/run_result'
+require_relative 'compat/parity/comparison'
+require_relative 'compat/parity/harness'

data/lib/eco/api/usecases/graphql/helpers/location/command/end_points/optimizations.rb

@@ -29,7 +29,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
             messages
           }
           draft { # rubocop:disable Style/BlockDelimiters
-            ___Ecoportal__API__GraphQL__Fragment__LocationDraft
+            spread :LocationDraft
           }
         }
       end
@@ -44,7 +44,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
             messages
           }
           draft { # rubocop:disable Style/BlockDelimiters
-            ___Ecoportal__API__GraphQL__Fragment__LocationDraft
+            spread :LocationDraft
           }
         }
       end
@@ -54,7 +54,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
           clientMutationId
           ok
           error { # rubocop:disable Style/BlockDelimiters
-            ___Ecoportal__API__GraphQL__Fragment__LocationsError
+            spread :LocationsError
           }
           errors { # rubocop:disable Style/BlockDelimiters
             details
@@ -69,7 +69,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
               __typename
             }
             error { # rubocop:disable Style/BlockDelimiters
-              ___Ecoportal__API__GraphQL__Fragment__LocationsError
+              spread :LocationsError
             }
           }
         }

data/lib/eco/api/usecases/graphql/helpers/pages/copying.rb

@@ -0,0 +1,71 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  module Pages
+    # Native GraphQL re-expression of OozeSamples::HelpersMigration::Copying.
+    #
+    # Provides the "pair source fields to destination fields and copy their
+    # content across" flow used by the native migration case. Pairing is delegated
+    # to `TypedFieldsPairing`; the per-field content copy (`copy_field_content`)
+    # dispatches on the GraphQL DataField TYPE STRING (PlainText/Select/Date/...),
+    # mirroring how OozeHandlers#merge_values ports the v2 type-class dispatch.
+    #
+    # Only the generic-typed-pairing flow is ported (the v2 regex/JSON hooked-field
+    # mapping — `copy_hooked_fields` / `with_src_dst_field_pair` — is a later
+    # increment and is intentionally omitted here).
+    module Copying
+      include Eco::Language::AuxiliarLogger
+      include Eco::API::UseCases::GraphQL::Helpers::Pages::Shortcuts
+
+      def session
+        defined?(super) ? super : @session
+      end
+
+      # Pair the same-type/same-label fields of `src` and `dst`, and copy the
+      # content of each pair from source to destination.
+      #
+      # @param src [Object] the source page model.
+      # @param dst [Object] the destination (draft) page model.
+      # @param src_excluded [Array] source fields to exclude from pairing.
+      # @param dst_excluded [Array] destination fields to exclude from pairing.
+      # @param exclude_ximport [Boolean] skip ximport-marked fields.
+      # @yield [src_fld, dst_fld, pairing] optional post-copy callback per pair.
+      # @return [TypedFieldsPairing] the tracker (unpaired / multi-pair inspection).
+      def copy_generic_paired_fields(src, dst, src_excluded: [], dst_excluded: [], exclude_ximport: false)
+        TypedFieldsPairing.new(
+          src,
+          dst,
+          src_excluded:    src_excluded,
+          dst_excluded:    dst_excluded,
+          exclude_ximport: exclude_ximport
+        ).tap do |pairing|
+          pairing.each_pair do |src_fld, dst_fld|
+            copy_field_content(src_fld, dst_fld)
+            yield(src_fld, dst_fld, pairing) if block_given?
+          end
+        end
+      end
+
+      # Copy the content of `src` into `dst`, dispatching on the GraphQL DataField
+      # TYPE STRING. `src` and `dst` are guaranteed to be the same type by the
+      # pairing. Types with no meaningful/copyable content (or whose native setter
+      # is not yet supported) are left untouched.
+      #
+      # @param src [#type] the source data field.
+      # @param dst [#type] the destination data field.
+      # @return [Object] result of the per-type copy (or a "won't copy" marker).
+      def copy_field_content(src, dst)
+        case src.type.to_s
+        when 'PlainText', 'Number', 'Date', 'Gauge'
+          dst.value = src.value
+        when 'RichText'
+          dst.content = src.content
+        when 'Select'
+          dst.select_option(*src.selected_options.map { |opt| opt['id'] })
+        when 'CrossReference'
+          dst.page_ids = src.page_ids
+        else
+          "won't copy"
+        end
+      end
+    end
+  end
+end