ecoportal-api-graphql 1.3.9 → 1.3.11

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

@@ -0,0 +1,59 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # One structural change between two snapshots of the same page/template.
+        #
+        # Deliberately command-ready: op + kind + id + before/after is enough for a later pass to
+        # synthesise the matching WorkflowCommand (editStage / addField / removeField /
+        # editFieldConfiguration / addSelectFieldOption / …) — the "portable commit".
+        #
+        # op:   :added | :removed | :changed | :moved
+        # kind: :stage | :section | :field | :option | :field_config | :gauge_stop
+        #
+        # parent_id: id of the owning entity when the change is nested and the child id alone is
+        # not enough to address a command. Set for :option changes (the parent data field id) so a
+        # synthesiser can emit add/edit/removeSelectFieldOption without re-deriving it; also for
+        # :field_config (the data field id) and :gauge_stop (the gauge field id).
+        #
+        # by_type: for :field_config changes, the `byType` sub-hash key (e.g. :gauge, :select, :date)
+        # under which the typed editFieldConfiguration property is nested. nil for other kinds.
+        #
+        # owner_id: the id of the GRANDPARENT node, when a create needs a second structural back-ref
+        # that parent_id alone cannot carry. Set for an ADDED :field (parent_id = its section id,
+        # owner_id = its stage id) because addField requires BOTH sectionId and stageId (both
+        # NON_NULL in the schema). nil for every other kind/op.
+        Change = Struct.new(:op, :kind, :id, :label, :path, :attribute, :before, :after, :parent_id,
+                            :by_type, :owner_id, keyword_init: true) do
+          def to_h
+            {
+              op: op, kind: kind, id: id, label: label, path: path,
+              attribute: attribute, before: before, after: after, parent_id: parent_id,
+              by_type: by_type, owner_id: owner_id
+            }.compact
+          end
+
+          # One-line human description for a changelog / ticket comment.
+          def description
+            case op
+            when :added   then "+ #{kind} '#{label}' added#{at_path}"
+            when :removed then "- #{kind} '#{label}' removed#{at_path}"
+            when :changed then "~ #{kind} '#{label}' #{attribute}: #{fmt(before)} -> #{fmt(after)}#{at_path}"
+            when :moved   then "> #{kind} '#{label}' moved: #{fmt(before)} -> #{fmt(after)}"
+            end
+          end
+
+          private
+
+          def at_path
+            path && !path.empty? ? "  (#{path})" : ''
+          end
+
+          def fmt(value)
+            value.nil? ? 'nil' : value.inspect
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,329 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Diff
+        # Turns a set of `Diff::Change` objects (from `VersionDiff`) into an ordered batch of built
+        # `WorkflowCommand` hashes — the replayable "commit".
+        #
+        #   changes  = VersionDiff.new(v1, v2).changes
+        #   synth    = CommandSynthesizer.new(changes)
+        #   synth.commands     # => [{ editFieldConfiguration: {...} }, { removeField: {...} }, ...]
+        #   synth.unsupported  # => [Change, ...]  (change kinds/ops with no matching command)
+        #
+        # SCOPE — self-version diff by default. The ids carried by each Change are REAL server ids of
+        # the SAME object across two of its own versions, so they can be replayed as-is. For a
+        # cross-object diff (UAT<->PROD, page<->template) every id in the emitted commands must first
+        # be translated through a pairing map before replay.
+        #
+        # RESOLVER — some edits address a TARGET node by an id the Change does not carry (a field
+        # move needs the destination *section id*; a section move needs the destination *stage id*).
+        # `VersionDiff` records those targets by their human key (section heading, stage name) because
+        # that is all a structural diff knows. Pass a `resolver` that maps
+        # `resolve(kind, key) => id` (e.g. the pairing engine's ledger, or a lookup built from the
+        # target doc) and those moves become supported. WITHOUT a resolver they stay UNSUPPORTED —
+        # the synthesiser never guesses a target id.
+        #
+        # ORDERING — structure before children, and within a kind: removes, then adds, then moves,
+        # then edits. Structural creates (stages, sections, fields) precede the option-level edits
+        # that depend on them, so a straight left-to-right replay stays valid.
+        #
+        # SAFETY — a change with no faithful command is NEVER guessed. It is collected into
+        # `unsupported` for the caller to inspect. In particular a field *type* change has no edit
+        # command in the schema (there is no editFieldType), so it is reported as unsupported rather
+        # than silently rebuilt (a rebuild would drop the field's data and history).
+        class CommandSynthesizer
+          # Emit order: structure first (stages -> sections -> fields), then options; and within a
+          # kind, removes -> adds -> moves -> edits, so a straight left-to-right replay stays valid.
+          KIND_ORDER = { stage: 0, section: 1, field: 2, field_config: 3, gauge_stop: 4, option: 5 }.freeze
+          OP_ORDER   = { removed: 0, added: 1, moved: 2, changed: 3 }.freeze
+
+          # @param changes  [Array<Change>]
+          # @param resolver [#resolve, nil] maps (kind, human-key) -> target id for move commands.
+          #   Any object answering `resolve(kind, key)` (returning an id or nil). When nil, moves
+          #   that need a target id are reported as unsupported.
+          # @param thread_placeholders [Boolean] when true, structural creates (addStage/addSection/
+          #   addField) emit a client-chosen `placeholderId`, and any later command in the SAME batch
+          #   that references a node created here substitutes that placeholder for the (target-invalid)
+          #   source id. This keeps add-then-reference sequences self-consistent within one
+          #   executeWorkflowCommands call. Off by default (self-version replay uses the real ids).
+          def initialize(changes, resolver: nil, thread_placeholders: false)
+            @changes             = Array(changes)
+            @resolver            = resolver
+            @thread_placeholders = thread_placeholders
+            @unsupported         = []
+          end
+
+          # Ordered Array of built command hashes (each `{ commandKey => {..input..} }`).
+          def commands
+            @commands ||= build_all
+          end
+
+          # Changes that could not be mapped to a command. Populated as a side effect of `commands`.
+          def unsupported
+            commands
+            @unsupported
+          end
+
+          private
+
+          # Group by (kind, op) and emit in a dependency-safe order:
+          # stages -> sections -> fields -> options, and remove -> add -> move -> change within each.
+          def build_all
+            build_placeholder_map
+            ordered = @changes.sort_by { |c| [KIND_ORDER.fetch(c.kind, 99), OP_ORDER.fetch(c.op, 99)] }
+            # command_for may return a single built hash, an Array of them (a move that emits
+            # remove+add), or nil (unsupported). Normalise each to a list, flatten, drop nils.
+            ordered.flat_map { |change| wrap(command_for(change)) }
+          end
+
+          # When threading is on, assign a deterministic placeholderId to every ADDED structural
+          # node (stage/section/field), keyed by its source id. A later command in this batch that
+          # references such an id is rewritten to the placeholder (the source id is not valid on the
+          # target). Threading OFF -> empty map -> `ref`/`placeholder_for` are no-ops.
+          def build_placeholder_map
+            @placeholders = {}
+            return unless @thread_placeholders
+
+            prefixes = { stage: 'stg', section: 'sec', field: 'fld' }
+            @changes.select { |c| c.op == :added && prefixes.key?(c.kind) }.each_with_index do |change, i|
+              next if change.id.nil?
+
+              @placeholders[change.id] = "ph_#{prefixes[change.kind]}_#{i}"
+            end
+          end
+
+          # The placeholder token for a node created in THIS batch, or nil if it was not.
+          def placeholder_for(id)
+            @placeholders[id]
+          end
+
+          # Reference an id the way a sibling command must: the batch-local placeholder if the node
+          # is being created here, otherwise the id as-is (a pre-existing target node).
+          def ref(id)
+            placeholder_for(id) || id
+          end
+
+          def command_for(change)
+            case change.kind
+            when :stage        then stage_command(change)
+            when :section      then section_command(change)
+            when :field        then field_command(change)
+            when :field_config then field_config_command(change)
+            when :gauge_stop   then gauge_stop_command(change)
+            when :option       then option_command(change)
+            else unsupported!(change)
+            end
+          end
+
+          # --- stage ---------------------------------------------------------
+
+          def stage_command(change)
+            case change.op
+            when :added   then build(:addStage, name: change.label, placeholderId: placeholder_for(change.id))
+            when :removed then build(:removeStage, stageId: change.id)
+            when :moved   then build(:moveStage, stageId: change.id, ordering: change.after)
+            when :changed
+              return build(:editStage, stageId: change.id, name: change.after) if change.attribute == 'name'
+
+              unsupported!(change)
+            else unsupported!(change)
+            end
+          end
+
+          # --- section -------------------------------------------------------
+
+          def section_command(change)
+            case change.op
+            when :added   then add_section(change)
+            when :removed then build(:removeSection, sectionId: change.id)
+            when :moved   then section_move(change)
+            when :changed
+              return build(:editSectionHeader, sectionId: change.id, header: change.after) if change.attribute == 'heading'
+
+              unsupported!(change)
+            else unsupported!(change)
+            end
+          end
+
+          # An added section is created with addSection (layout/placeholder), then WIRED to its
+          # parent stage with a follow-up addStageSection — addSection itself has no stage-id key in
+          # the schema, the stage<->section link is a separate command. The stage back-ref threads
+          # through `ref`: the parent stage's placeholder when it is created in this same batch, else
+          # its real id. When the parent stage id is unknown (a hand-assembled Change with no
+          # parent_id), only addSection is emitted — the historical behaviour, unchanged.
+          def add_section(change)
+            cmds = [build(:addSection, placeholderId: placeholder_for(change.id))]
+            cmds << build(:addStageSection, stageId: ref(change.parent_id), sectionId: ref(change.id)) unless change.parent_id.nil?
+            cmds
+          end
+
+          # A section 'move' is a stage reassignment: detach from the old stage, attach to the new.
+          # Both need a stage id; VersionDiff records only the stage NAME (before/after), so a
+          # resolver is required to turn those names into ids. Emitted as two commands so the replay
+          # is faithful (remove then add). Without a resolver -> unsupported (never guess a stage id).
+          def section_move(change)
+            return unsupported!(change) if change.attribute != 'stage'
+
+            from_id = resolve(:stage, change.before)
+            to_id   = resolve(:stage, change.after)
+            return unsupported!(change) if to_id.nil?
+
+            cmds = []
+            cmds << build(:removeStageSection, stageId: from_id, sectionId: change.id) if from_id
+            cmds << build(:addStageSection, stageId: to_id, sectionId: change.id)
+            cmds
+          end
+
+          # --- field ---------------------------------------------------------
+
+          def field_command(change)
+            case change.op
+            when :added   then add_field(change)
+            when :removed then build(:removeField, id: change.id)
+            when :moved   then field_move(change)
+            when :changed then field_edit(change)
+            else unsupported!(change)
+            end
+          end
+
+          # An added field carries its structural back-refs: sectionId (parent_id) and stageId
+          # (owner_id) — both NON_NULL on the schema's addField input. Each threads through `ref`:
+          # the parent's placeholder when the parent stage/section is created in this same batch,
+          # else its real id. When a back-ref id is unknown (a hand-assembled Change without
+          # parent_id/owner_id) that key is simply omitted (AddField.build compacts nils) — the
+          # historical behaviour, unchanged.
+          def add_field(change)
+            build(:addField,
+                  label:         change.label,
+                  sectionId:     (ref(change.parent_id) unless change.parent_id.nil?),
+                  stageId:       (ref(change.owner_id) unless change.owner_id.nil?),
+                  placeholderId: placeholder_for(change.id))
+          end
+
+          def field_edit(change)
+            return build(:editFieldConfiguration, data_field_id: change.id, label: change.after) if change.attribute == 'label'
+
+            # Field TYPE change: no editFieldType command exists in the schema. Do not synthesise a
+            # remove+add (it would destroy the field's data) — report it for manual handling.
+            unsupported!(change)
+          end
+
+          # A field 'move' is a section reassignment. moveField needs the destination SECTION id;
+          # VersionDiff records only the section HEADING (before/after). A resolver turns the target
+          # heading into a section id. Without one -> unsupported (never guess a section id).
+          def field_move(change)
+            return unsupported!(change) if change.attribute != 'section'
+
+            section_id = resolve(:section, change.after)
+            return unsupported!(change) if section_id.nil?
+
+            build(:moveField, id: change.id, sectionId: section_id)
+          end
+
+          # --- typed field configuration (byType) ----------------------------
+
+          # A per-type field-configuration change maps to editFieldConfiguration with the changed
+          # property nested under its `byType` sub-hash (e.g. { gauge: { max: 5.0 } }). VersionDiff
+          # stamps `by_type` (the sub-hash key) and `parent_id` (the data field id). Without a
+          # by_type key we cannot address the typed input -> unsupported (never guessed).
+          def field_config_command(change)
+            return unsupported!(change) unless change.op == :changed
+
+            field_id = change.parent_id || change.id
+            by_type  = change.by_type
+            return unsupported!(change) if field_id.nil? || by_type.nil? || change.attribute.nil?
+
+            body = { by_type => { change.attribute.to_sym => change.after } }
+            build(:editFieldConfiguration, data_field_id: ref(field_id), byType: body)
+          end
+
+          # --- gauge stops ---------------------------------------------------
+
+          # Gauge stops address the parent gauge field id (parent_id). Add needs threshold+color
+          # (carried on change.after); edit/remove need the stop id (change.id).
+          def gauge_stop_command(change)
+            field_id = change.parent_id
+            return unsupported!(change) if field_id.nil?
+
+            field_ref = ref(field_id)
+            case change.op
+            when :added   then add_gauge_stop(change, field_ref)
+            when :removed then build(:removeGaugeFieldStop, data_field_id: field_ref, stop_id: change.id)
+            when :changed then edit_gauge_stop(change, field_ref)
+            else unsupported!(change)
+            end
+          end
+
+          def add_gauge_stop(change, field_id)
+            spec = change.after
+            return unsupported!(change) unless spec.is_a?(Hash)
+
+            build(:addGaugeFieldStop, data_field_id: field_id, threshold: spec[:threshold], color: spec[:color])
+          end
+
+          def edit_gauge_stop(change, field_id)
+            case change.attribute
+            when 'threshold' then build(:editGaugeFieldStop, data_field_id: field_id, stop_id: change.id, threshold: change.after)
+            when 'color'     then build(:editGaugeFieldStop, data_field_id: field_id, stop_id: change.id, color: change.after)
+            else unsupported!(change)
+            end
+          end
+
+          # --- option --------------------------------------------------------
+
+          def option_command(change)
+            field_id = change.parent_id
+            return unsupported!(change) if field_id.nil?
+
+            field_ref = ref(field_id)
+            case change.op
+            when :added   then build(:addSelectFieldOption, data_field_id: field_ref, label: change.label)
+            when :removed then build(:removeSelectFieldOption, data_field_id: field_ref, option_id: change.id)
+            when :changed then edit_option(change, field_ref)
+            else unsupported!(change)
+            end
+          end
+
+          def edit_option(change, field_id)
+            case change.attribute
+            when 'label'  then build(:editSelectFieldOption, data_field_id: field_id, option_id: change.id, label: change.after)
+            when 'weight' then build(:editSelectFieldOption, data_field_id: field_id, option_id: change.id, weight: change.after)
+            else unsupported!(change)
+            end
+          end
+
+          # --- helpers -------------------------------------------------------
+
+          def build(command_key, **kwargs)
+            Ecoportal::API::GraphQL::Input::WorkflowCommand.build(command_key, **kwargs)
+          end
+
+          # Ask the resolver for the target id of `key` (a heading / stage name). Returns nil when
+          # there is no resolver or it cannot resolve — callers treat nil as "unsupported".
+          def resolve(kind, key)
+            return nil if key.nil? || @resolver.nil?
+
+            @resolver.resolve(kind, key)
+          end
+
+          # Normalise a command_for result (nil | Hash | Array<Hash>) into a flat list of hashes.
+          # A built command is a Hash, so we must NOT use Kernel#Array (it would splat a Hash into
+          # key/value pairs).
+          def wrap(result)
+            case result
+            when nil   then []
+            when Array then result.compact
+            else [result]
+            end
+          end
+
+          # Record an unmappable change and return nil (filtered out of the command list).
+          def unsupported!(change)
+            @unsupported << change
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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