ecoportal-api-graphql 1.3.10 → 1.3.11

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

@@ -0,0 +1,104 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        module Pairing
+          # Weak pairing SIGNALS combined into a confidence score. Each signal scores a candidate
+          # (source-field-doc, target-field-doc) pair in 0.0..1.0. NONE is ground truth on its own —
+          # per the domain reference genomeSignature is strong-but-fallible (6 documented failure
+          # modes: manual/no-platform-support, new features never added, wrong for select options,
+          # wrongly syncs checklists, re-used/re-purposed fields, incomplete data-loss accounting).
+          # So genome is ONE signal among several, weighted highest but able to be outvoted /
+          # confirmed by type+label+options. The Engine aggregates these with `WEIGHTS`.
+          module Signals
+            module_function
+
+            # Relative weights (need not sum to 1; the Engine normalises by the weights that applied).
+            WEIGHTS = {
+              genome:  0.5,
+              type:    0.2,
+              label:   0.2,
+              options: 0.1
+            }.freeze
+
+            # genomeSignature match. Strong but fallible, so a MATCH scores high (not 1.0) and a
+            # MISMATCH scores 0 rather than vetoing (the field may have been re-purposed keeping its
+            # genome, or genome may be absent on newer field types). Returns nil when neither side
+            # carries a genome — the signal simply does not apply and is excluded from the average.
+            def genome(source, target)
+              a = source['genomeSignature']
+              b = target['genomeSignature']
+              return nil if blank?(a) && blank?(b)
+              return 0.0 if blank?(a) || blank?(b)
+
+              a == b ? 1.0 : 0.0
+            end
+
+            # Field type (__typename) equality. A type change is a strong DISQUALIFIER for a data
+            # pairing (you cannot faithfully migrate PlainText data into a Gauge), so a mismatch is 0.
+            def type(source, target)
+              ta = type_of(source)
+              tb = type_of(target)
+              return nil if ta.nil? && tb.nil?
+
+              ta == tb ? 1.0 : 0.0
+            end
+
+            # Label similarity — exact (case/space-insensitive) = 1.0, else a token-overlap
+            # (Jaccard) score, so `Date logged` vs `Date of sign-off` still gets partial credit
+            # (a re-purpose candidate the human should adjudicate rather than an auto-accept).
+            def label(source, target)
+              a = normalise(source['label'])
+              b = normalise(target['label'])
+              return nil if a.empty? && b.empty?
+              return 1.0 if a == b && !a.empty?
+
+              jaccard(a.split, b.split)
+            end
+
+            # Select-option overlap by VALUE (primary) / label (auxiliary) — the CORRECT option
+            # identity, never genome. Returns nil for non-select fields (no options either side).
+            def options(source, target)
+              a = option_keys(source)
+              b = option_keys(target)
+              return nil if a.empty? && b.empty?
+
+              jaccard(a, b)
+            end
+
+            def type_of(field)
+              field['__typename'] || field['type']
+            end
+
+            def normalise(value)
+              value.to_s.strip.downcase.gsub(/\s+/, ' ')
+            end
+
+            def option_keys(field)
+              Array(field['options']).filter_map do |o|
+                next unless o.is_a?(Hash)
+
+                normalise(o['value'] || o['label'] || o['name'])
+              end.reject(&:empty?)
+            end
+
+            # Jaccard similarity of two token collections (|∩| / |∪|). 0.0 when both empty.
+            def jaccard(list_a, list_b)
+              set_a = list_a.to_a.uniq
+              set_b = list_b.to_a.uniq
+              return 0.0 if set_a.empty? && set_b.empty?
+
+              inter = (set_a & set_b).size.to_f
+              union = (set_a | set_b).size
+              union.zero? ? 0.0 : inter / union
+            end
+
+            def blank?(value)
+              value.nil? || value.to_s.strip.empty?
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # Composable configuration for a diff. There is NO single diff — different processes need
+        # different modes (see `template_diff_pairing_domain.md` §8). A `Strategy` is the value object
+        # that names the axes, consumed by the diff front-end (`VersionDiff` / `CrossObjectDiff`) and
+        # by `Deploy`.
+        #
+        # Axes:
+        #
+        # * **pairing** — how counterpart objects are identified across the two snapshots:
+        #     :id         same object, retained Mongo ids (self-version) — NO equivalence needed;
+        #     :genome     pair by genomeSignature (cross-object; a strong-but-fallible signal);
+        #     :type_label pair by __typename + label (cross-object; the TypedFieldsPairing precedent);
+        #     :assisted   the full multi-signal `Pairing::Engine` (+ `Ledger`), human-in-the-loop
+        #                 for ambiguous/unmatched — the general cross-object case.
+        #   `:id` is the default and keeps the existing self-version behaviour untouched.
+        #
+        # * **scope** — which change kinds are emitted:
+        #     :structural    stages / sections / fields (add/remove/move/relabel/retype) + options + gauge;
+        #     :config_only   field configuration (byType), select options, gauge stops — NOT structure;
+        #     :data_migration field<->field data pairing only (structure-agnostic): pairings + type/label
+        #                     changes on paired fields, no add/remove of scaffolding.
+        #
+        # * **move_sensitive** — when false, section/stage MOVES are suppressed (a section-agnostic
+        #   diff that only cares about a field's data pairing, not where it now lives).
+        #
+        # * **intent** — the consuming process (documentation only; does not alter emission, but lets a
+        #   caller/`Deploy` branch on it):
+        #     :changelog     what changed, for a ticket / review checklist;
+        #     :deploy        UAT->PROD replay delta (drives placeholderId threading ON in Deploy);
+        #     :sync_readiness can this register/subset be synced to the active template.
+        #
+        # Cross-object pairings (:genome/:type_label/:assisted) require a pairing map to translate the
+        # two id-spaces before change emission — see `CrossObjectDiff`. `:id` needs no map.
+        class Strategy
+          PAIRINGS        = %i[id genome type_label assisted].freeze
+          SCOPES          = %i[structural config_only data_migration].freeze
+          INTENTS         = %i[changelog deploy sync_readiness].freeze
+
+          # Change KINDS considered structure vs configuration — used to filter by `scope`.
+          STRUCTURAL_KINDS = %i[stage section field].freeze
+          CONFIG_KINDS     = %i[field_config option gauge_stop].freeze
+
+          attr_reader :pairing, :scope, :intent
+
+          def initialize(pairing: :id, scope: :structural, move_sensitive: true, intent: :changelog)
+            @pairing        = validate!(:pairing, pairing, PAIRINGS)
+            @scope          = validate!(:scope, scope, SCOPES)
+            @move_sensitive = move_sensitive ? true : false
+            @intent         = validate!(:intent, intent, INTENTS)
+          end
+
+          # The default self-version strategy (id-paired, structural, move-aware, changelog). This is
+          # exactly the behaviour `VersionDiff` had before Phase 4 — used when no strategy is passed.
+          def self.default
+            new
+          end
+
+          def move_sensitive?
+            @move_sensitive
+          end
+
+          # True when pairing does NOT rely on retained ids — the two snapshots live in different
+          # id-spaces and need a pairing map (`CrossObjectDiff`) before change emission.
+          def cross_object?
+            @pairing != :id
+          end
+
+          # Should a change of this KIND be emitted under this scope?
+          def emit_kind?(kind)
+            case @scope
+            when :structural     then true
+            when :config_only    then CONFIG_KINDS.include?(kind)
+            when :data_migration then kind == :field # field-level data pairing only
+            end
+          end
+
+          # Should a :moved change be emitted? Suppressed when move-insensitive, or under a scope that
+          # ignores scaffolding placement (config_only / data_migration never care about moves).
+          def emit_move?
+            move_sensitive? && @scope == :structural
+          end
+
+          # Filter a raw change-set to what this strategy emits (scope + move-sensitivity). The diff
+          # front-ends compute the full change-set once and let the strategy decide what survives.
+          def filter(changes)
+            Array(changes).select do |change|
+              next false unless emit_kind?(change.kind)
+              next false if change.op == :moved && !emit_move?
+
+              true
+            end
+          end
+
+          def to_h
+            { pairing: @pairing, scope: @scope, move_sensitive: move_sensitive?, intent: @intent }
+          end
+
+          private
+
+          def validate!(axis, value, allowed)
+            sym = value&.to_sym
+            return sym if allowed.include?(sym)
+
+            raise ArgumentError, "invalid #{axis}: #{value.inspect} (expected one of #{allowed.inspect})"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,332 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # Self-version diff: two snapshots of the SAME page/template (same Mongo ids).
+        #
+        # Because the object keeps its ids across versions, pairing is EXACT (match by id) — no
+        # equivalence matching needed. This is the "what did this ticket change to the UAT template"
+        # tool, and the basis of a portable changelog ("commit") that — once id-translated through a
+        # pairing map — can be replayed onto PROD. Cross-object diff (UAT<->PROD, page<->template)
+        # is a different, harder problem handled by the pairing engine (not here).
+        #
+        # Operates on the raw page/template doc (the JSON the gem returns for a page/template), so it
+        # is a shared, session-less capability usable by admin/troubleshooting/integration/QA alike.
+        #
+        #   diff = Diff::VersionDiff.new(before_doc, after_doc)
+        #   diff.changes          # => [Change, ...]
+        #   diff.summary          # => { added:, removed:, changed:, moved:, total: }
+        #   diff.changelog        # => ["~ field 'Severity' ...", ...]
+        #
+        # MODALITIES — pass a `Diff::Strategy` to select a scope / move-sensitivity. The default
+        # strategy (id-paired, structural, move-aware, changelog) reproduces the pre-Phase-4 behaviour
+        # exactly, so `VersionDiff.new(before, after).changes` is unchanged. A narrower scope
+        # (`:config_only`, `:data_migration`) or a move-insensitive strategy filters the SAME computed
+        # change-set — the pairing is still by-id here (`VersionDiff` is the `:id` pairing front-end).
+        # Cross-object pairings (:genome/:type_label/:assisted) are handled by `CrossObjectDiff`.
+        class VersionDiff
+          # Typed field-configuration properties that this diff EMITS, keyed by the field's
+          # `__typename`. Each entry maps a `byType` input key (the sub-hash the schema's
+          # `editFieldConfiguration.byType` accepts) to the list of doc property names that make up
+          # that sub-hash. Only pairs where the READ property name matches the WRITE (byType) input
+          # key EXACTLY are listed here — this diff never fabricates a config change it cannot map
+          # back to a real command input.
+          #
+          # Deliberately conservative: e.g. PlainText carries `multiline` in the read model but the
+          # `plainText` byType input has no `multiline` key (it exposes `maxLength`), so PlainText
+          # config is NOT emitted here (it would be unmappable). Likewise `required` has no
+          # editFieldConfiguration key at all, so a `required` flip is not a config change we emit.
+          BYTYPE_CONFIG = {
+            'Gauge'  => { gauge:  %w[max] },
+            'Select' => { select: %w[dataType multiple flat other otherDesc] },
+            'Date'   => { date:   %w[showTime pastOnly todayButton] }
+          }.freeze
+
+          def initialize(before_doc, after_doc, strategy: Strategy.default)
+            @before   = before_doc || {}
+            @after    = after_doc  || {}
+            @strategy = strategy || Strategy.default
+          end
+
+          # The change-set, filtered by the strategy's scope + move-sensitivity. The full set is
+          # computed once (`all_changes`); the strategy decides what survives. The default strategy
+          # keeps everything (the historical behaviour).
+          def changes
+            @changes ||= @strategy.filter(all_changes)
+          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
+            }
+          end
+
+          def changelog
+            changes.map(&:description)
+          end
+
+          def to_h
+            { summary: summary, changes: changes.map(&:to_h) }
+          end
+
+          private
+
+          # The complete id-paired change-set (all kinds, all ops) before any strategy filtering.
+          def all_changes
+            stage_changes + section_changes + field_changes + option_changes +
+              field_config_changes + gauge_stop_changes
+          end
+
+          # Generic set-diff over an index {id => info}. Emits added/removed (label/path pulled from
+          # info via the given procs) and delegates matched-id comparison to the block.
+          #
+          # `parent:` (optional) is a proc mapping an entry's info to the id of its OWNING node — the
+          # section id for a field, the stage id for a section. Recorded on ADDED changes as
+          # `parent_id` so the synthesiser can wire the structural back-ref (addField.sectionId /
+          # addStageSection.stageId), threading through a placeholder when the parent is created in
+          # the same batch. nil (default) means no parent id is known/recorded — the historical
+          # behaviour, unchanged.
+          def diff_index(kind, before_idx, after_idx, label:, path:, parent: nil, owner: nil, &compare)
+            procs   = { label: label, path: path, parent: parent, owner: owner }
+            removed = (before_idx.keys - after_idx.keys).map { |id| removed_change(kind, id, before_idx[id], procs) }
+            added   = (after_idx.keys - before_idx.keys).map { |id| added_change(kind, id, after_idx[id], procs) }
+            matched = (before_idx.keys & after_idx.keys).flat_map { |id| Array(compare.call(id, before_idx[id], after_idx[id])) }
+            removed + added + matched
+          end
+
+          def removed_change(kind, id, info, procs)
+            Change.new(op: :removed, kind: kind, id: id, label: procs[:label].call(info), path: procs[:path].call(info))
+          end
+
+          def added_change(kind, id, info, procs)
+            Change.new(op: :added, kind: kind, id: id, label: procs[:label].call(info), path: procs[:path].call(info),
+                       parent_id: procs[:parent]&.call(info), owner_id: procs[:owner]&.call(info))
+          end
+
+          def stage_changes
+            diff_index(:stage, index_stages(@before), index_stages(@after),
+                       label: ->(s) { s['name'] }, path: ->(s) { s['name'] }) do |id, b, a|
+              cmp = []
+              cmp << changed(:stage, id, a['name'], a['name'], 'name', b['name'], a['name']) if b['name'] != a['name']
+              cmp << moved(:stage, id, a['name'], 'ordering', b['ordering'], a['ordering']) if b['ordering'] != a['ordering']
+              cmp
+            end
+          end
+
+          def section_changes
+            diff_index(:section, index_sections(@before), index_sections(@after),
+                       label: ->(s) { s[:heading] }, path: ->(s) { s[:path] },
+                       parent: ->(s) { s[:stage_id] }) do |id, b, a|
+              cmp = []
+              cmp << changed(:section, id, a[:heading], a[:path], 'heading', b[:heading], a[:heading]) if b[:heading] != a[:heading]
+              cmp << moved(:section, id, a[:heading], 'stage', b[:stage], a[:stage]) if b[:stage] != a[:stage]
+              cmp
+            end
+          end
+
+          def field_changes
+            diff_index(:field, index_fields(@before), index_fields(@after),
+                       label: ->(f) { f[:label] }, path: ->(f) { f[:path] },
+                       parent: ->(f) { f[:section_id] }, owner: ->(f) { f[:stage_id] }, &method(:compare_field))
+          end
+
+          def compare_field(id, before, after)
+            cmp = []
+            cmp << changed(:field, id, after[:label], after[:path], 'label', before[:label], after[:label]) if before[:label] != after[:label]
+            cmp << changed(:field, id, after[:label], after[:path], 'type', before[:type], after[:type]) if before[:type] != after[:type]
+            cmp << moved(:field, id, after[:label], 'section', before[:section], after[:section]) if before[:section] != after[:section]
+            cmp
+          end
+
+          def option_changes
+            bf = index_fields(@before)
+            af = index_fields(@after)
+            (bf.keys & af.keys).flat_map do |fid|
+              options_diff(fid, af[fid][:path], bf[fid][:field], af[fid][:field])
+            end
+          end
+
+          def options_diff(field_id, path, before_field, after_field)
+            diff_index(:option, index_options(before_field), index_options(after_field),
+                       label: ->(o) { o[:label] }, path: ->(_o) { path }) do |k, b, a|
+              cmp = []
+              cmp << changed(:option, k, a[:label], path, 'label', b[:label], a[:label], field_id) if b[:label] != a[:label]
+              cmp << changed(:option, k, a[:label], path, 'weight', b[:weight], a[:weight], field_id) if b[:weight] != a[:weight]
+              cmp
+            end.each { |c| c.parent_id ||= field_id }
+          end
+
+          # --- typed field configuration (byType) ---------------------------
+
+          # Per-type field-configuration changes (the `byType` body of editFieldConfiguration).
+          # Matched by retained field id (self-version). For each field type in BYTYPE_CONFIG, emit
+          # a `:field_config` change per changed property, carrying the byType key so the synthesiser
+          # can nest it under the right sub-hash. Properties absent from BYTYPE_CONFIG are ignored
+          # here (unmappable → never fabricated).
+          def field_config_changes
+            bf = index_fields(@before)
+            af = index_fields(@after)
+            (bf.keys & af.keys).flat_map do |fid|
+              config_diff_for_field(fid, bf[fid], af[fid])
+            end
+          end
+
+          def config_diff_for_field(field_id, before_info, after_info)
+            type = after_info[:type]
+            return [] if before_info[:type] != type # a type change is handled/blocked elsewhere
+
+            (BYTYPE_CONFIG[type] || {}).flat_map do |by_type, props|
+              props.filter_map do |prop|
+                bv = before_info[:field][prop]
+                av = after_info[:field][prop]
+                next if bv == av
+
+                config_change(field_id, after_info, by_type, prop, bv, av)
+              end
+            end
+          end
+
+          def config_change(field_id, after_info, by_type, prop, before, after) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :changed, kind: :field_config, id: field_id, label: after_info[:label],
+                       path: after_info[:path], attribute: prop, before: before, after: after,
+                       parent_id: field_id, by_type: by_type)
+          end
+
+          # --- gauge stops ---------------------------------------------------
+
+          # Gauge fields carry an ordered list of `stops` ({ id, threshold, color }). Diff them per
+          # gauge field, matched by retained stop id (self-version). Added / removed / changed
+          # (threshold or color). parent_id = the gauge field id (the stop commands address it).
+          def gauge_stop_changes
+            bf = index_fields(@before)
+            af = index_fields(@after)
+            (bf.keys & af.keys).flat_map do |fid|
+              next [] unless af[fid][:type] == 'Gauge' && bf[fid][:type] == 'Gauge'
+
+              stops_diff(fid, af[fid][:path], bf[fid][:field], af[fid][:field])
+            end
+          end
+
+          # Explicit add/remove/change diff (NOT the generic diff_index): an ADDED stop must carry
+          # its full spec (threshold + color) on the Change so addGaugeFieldStop can be built without
+          # re-reading the doc.
+          def stops_diff(field_id, path, before_field, after_field)
+            before_idx = index_stops(before_field)
+            after_idx  = index_stops(after_field)
+
+            removed = (before_idx.keys - after_idx.keys).map do |sid|
+              Change.new(op: :removed, kind: :gauge_stop, id: sid, label: before_idx[sid][:label],
+                         path: path, parent_id: field_id)
+            end
+            added = (after_idx.keys - before_idx.keys).map do |sid|
+              s = after_idx[sid]
+              Change.new(op: :added, kind: :gauge_stop, id: sid, label: s[:label], path: path,
+                         parent_id: field_id, after: { threshold: s[:threshold], color: s[:color] })
+            end
+            changed = (before_idx.keys & after_idx.keys).flat_map do |sid|
+              stop_attr_changes(field_id, sid, path, before_idx[sid], after_idx[sid])
+            end
+            removed + added + changed
+          end
+
+          def stop_attr_changes(field_id, stop_id, path, before, after)
+            cmp = []
+            cmp << stop_changed(field_id, stop_id, path, 'threshold', before[:threshold], after[:threshold]) if before[:threshold] != after[:threshold]
+            cmp << stop_changed(field_id, stop_id, path, 'color', before[:color], after[:color]) if before[:color] != after[:color]
+            cmp
+          end
+
+          def stop_changed(field_id, stop_id, path, attribute, before, after) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :changed, kind: :gauge_stop, id: stop_id, label: "#{attribute} #{after}".strip,
+                       path: path, attribute: attribute, before: before, after: after, parent_id: field_id)
+          end
+
+          # Stops keyed by id, carrying threshold + color (an ADD needs both to build the command).
+          def index_stops(field)
+            Array(field['stops']).each_with_object({}) do |s, h|
+              next unless s.is_a?(Hash) && s['id']
+
+              h[s['id']] = { threshold: s['threshold'], color: s['color'],
+                             label: "#{s['threshold']} #{s['color']}".strip }
+            end
+          end
+
+          # --- indexing helpers ---------------------------------------------
+
+          def index_stages(doc)
+            stages(doc).each_with_object({}) { |st, h| h[st['id']] = st if st['id'] }
+          end
+
+          def index_sections(doc)
+            out = {}
+            stages(doc).each do |st|
+              sections(st).each do |sec|
+                next unless sec['id']
+
+                out[sec['id']] = { heading: sec['heading'], stage: st['name'], stage_id: st['id'],
+                                   path: "#{st['name']} / #{sec['heading']}" }
+              end
+            end
+            out
+          end
+
+          def index_fields(doc)
+            out = {}
+            stages(doc).each do |st|
+              sections(st).each do |sec|
+                fields(sec).each do |f|
+                  next unless f['id']
+
+                  out[f['id']] = {
+                    field: f, label: f['label'], type: f['__typename'] || f['type'],
+                    section: sec['heading'], section_id: sec['id'], stage_id: st['id'],
+                    path: "#{st['name']} / #{sec['heading']} / #{f['label']}"
+                  }
+                end
+              end
+            end
+            out
+          end
+
+          # Options keyed by id when present, else by value (primary) / name (auxiliary) — the
+          # correct select-option identity (NOT genome).
+          def index_options(field)
+            Array(field['options']).each_with_object({}) do |o, h|
+              next unless o.is_a?(Hash)
+
+              key = o['id'] || o['value'] || o['label'] || o['name']
+              h[key] = { label: o['label'] || o['name'] || o['value'], weight: o['weight'] }
+            end
+          end
+
+          def stages(doc)
+            Array(doc['stages'])
+          end
+
+          def sections(stage)
+            Array(stage['sections'])
+          end
+
+          def fields(section)
+            Array(section['dataFields']) + Array(section['leftDataFields']) + Array(section['rightDataFields'])
+          end
+
+          def changed(kind, id, label, path, attribute, before, after, parent_id = nil) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :changed, kind: kind, id: id, label: label, path: path,
+                       attribute: attribute, before: before, after: after, parent_id: parent_id)
+          end
+
+          def moved(kind, id, label, attribute, before, after) # rubocop:disable Metrics/ParameterLists
+            Change.new(op: :moved, kind: kind, id: id, label: label,
+                       attribute: attribute, before: before, after: after)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Ecoportal
+  module API
+    class GraphQL
+      # Diff engines over the page/template model.
+      #
+      # `VersionDiff` handles the EASY, exact case — two snapshots of the SAME object (same ids),
+      # e.g. a UAT template at version N vs N+1 ("what did this ticket change"). The HARD case —
+      # pairing two DIFFERENT objects with different ids (UAT<->PROD, page<->template) — is an
+      # equivalence-matching problem handled by `Diff::Pairing` (multi-signal + learning ledger).
+      #
+      # `CommandSynthesizer` turns a change-set into an ordered WorkflowCommand batch (the replayable
+      # "commit"); `IdResolver` fills in move-target ids from a target doc; `Deploy` orchestrates
+      # diff -> commands -> apply, gating on the honest `unsupported` list.
+      #
+      # `Strategy` makes diffing a COMPOSABLE family (pairing x scope x move-sensitivity x intent);
+      # `CrossObjectDiff` is the cross-object front-end (pairs fields via `Pairing::Engine`, then
+      # emits the same `Change` output against the pairing map).
+      module Diff
+      end
+    end
+  end
+end
+
+require_relative 'diff/change'
+require_relative 'diff/strategy'
+require_relative 'diff/version_diff'
+require_relative 'diff/id_resolver'
+require_relative 'diff/command_synthesizer'
+require_relative 'diff/pairing/ledger'
+require_relative 'diff/pairing/candidate'
+require_relative 'diff/pairing/signals'
+require_relative 'diff/pairing/engine'
+require_relative 'diff/cross_object_diff'
+require_relative 'diff/deploy'

data/lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb

@@ -119,6 +119,7 @@ module Ecoportal
               __typename
               id                @skip(if: $only_content)
               label
+              genomeSignature   @skip(if: $only_content)
               deindex           @include(if: $content)
               linkedFieldConfig @skip(if: $only_content) {
                 crossReferenceId

data/lib/ecoportal/api/graphql/input/workflow_command/add_field.rb

@@ -1,18 +1,27 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Input
-        class WorkflowCommand
-          module AddField
-            SCHEMA_VERSION = '20260605'.freeze
-            VALID_KEYS = %i[placeholderId fieldType label stageId sectionId column].freeze
-
-            def self.build(**kwargs)
-              kwargs.slice(*VALID_KEYS).compact
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          module AddField
+            SCHEMA_VERSION = '20260605'.freeze
+            # VERIFIED against the live schema dump (WorkflowAddFieldInput, 20260605): the create
+            # command accepts ONLY these keys. There is NO `description` and NO `required` field on
+            # WorkflowAddFieldInput. `description` is instead a top-level key of
+            # WorkflowEditFieldConfigurationInput, so a field's description is persisted via a
+            # follow-up editFieldConfiguration command (see Builder::TemplateBuilder /
+            # Diff::CommandSynthesizer). `required` has NO input key anywhere in the schema (not on
+            # AddField, not on editFieldConfiguration top-level or any byType sub-input) and so
+            # cannot be persisted through the workflow command bus at all — callers must treat it as
+            # a read-only/unsupported attribute. Do NOT add these keys here (the server rejects them).
+            VALID_KEYS = %i[placeholderId fieldType label stageId sectionId column].freeze
+
+            def self.build(**kwargs)
+              kwargs.slice(*VALID_KEYS).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/mutation/action/archive.rb

@@ -29,7 +29,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/action/create.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/action/update.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end