eco-helpers 3.2.16 → 3.2.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bf8d3ba40b3f6731a9790d3068ecfd8396b13af79fd5a553aed7dafa5514236
-  data.tar.gz: 386c5c215aef1afb8e5ef4c8fb72aeddd6ec4c66bb89d569e9c579063128900f
+  metadata.gz: 9a51d3b328b3fda96aa2fa153f47481bad73417bc59b45000c7bea49d83d963f
+  data.tar.gz: 46a7268158b4d9d6695868ab2c89eb737764ee9896b53e956c2b08ffadb9c8a5
 SHA512:
-  metadata.gz: 9eaaaf9ecff40b6eb646adeceb8cc7115dacf998357206f9192ff4d6bf912067a90a915b93649ef49c99332c5655459fc599fec3a516f11c49951442bc836219
-  data.tar.gz: 0020a6441d4da68b5a3b80b82494197b2f4c21656dd5babbd143e8ac6302fcd09599eb68d68b9a32895dcd0bd76f6cf76ba96ae66f17706b30a9dbd5f1d61131
+  metadata.gz: 7ad1185638b499866d8052480b013cb46e2fd89d2cadf622bbe3e8392bdba50334019ca5ce08e969e8e53dc3f32d71eb7dfcf4246aec8524d9708862ab9ce5f2
+  data.tar.gz: ee15599fc00631f1e4f659df324f3b5a587d62b893f35ed436bd01b8c3d23c5ee1b8a72c55e615b890afce94a3bc80f51e4e2389449f89ba46a0b01031d93625

data/CHANGELOG.md

@@ -2,6 +2,123 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.2.17] - 2026-07-04
+
+Native GraphQL template build+maintenance + ooze-native migration (strangler-fig): pure,
+non-breaking additions built ALONGSIDE the OozeRedirect shim. No `OozeSamples::*` name is
+flipped/redirected and the shim is untouched. **Not yet published** — the template Deploy loop binds
+to the gem's `Diff` module (gem v1.3.11), which is tagged but unpublished.
+
+### Fixed
+
+- **`-no-email` double-send guard typo.** `Location::Command::Service::TreeUpdate#email_digest` set
+  `{worfklow: {no_email: true}}` (misspelled key) after sending, so the "don't send the digest twice"
+  guard never took effect. Corrected to `workflow`. (Note: the primary `-no-email` check on the same
+  method already used the correct key, so a single `-no-email` run was already suppressed.)
+- **Location command optimizations — dead fragment convention (live crash).**
+  `Helpers::Location::Command::EndPoints::Optimizations` referenced fragments via the removed
+  `___Const__Fragment` constant convention (`___Ecoportal__API__GraphQL__Fragment__LocationDraft` /
+  `…__LocationsError`), which the gem's registry-based fragments no longer expose as Ruby constants →
+  `uninitialized constant … Fragment::LocationDraft (NameError)` when building a locations-draft
+  `addCommands`/`create`/`publish` request. Crashed the live act-gov tagtree / org-structure sync.
+  Now `spread :LocationDraft` / `spread :LocationsError`, matching the gem.
+
+### Dependencies
+
+- **Raised floors to the fixed stack: `ecoportal-api-graphql >= 1.3.11`, `ecoportal-api-v2 >= 3.3.3`.**
+  Stops the stale gem 1.3.9 (missing the LocationStructure `updatedAt`/`createdAt` selection fixes from
+  1.3.10) and the buggy v2 3.3.2 (Ruby-3.x `DoubleModel` cascade `TypeError`) from resolving on
+  consumers — both crashed the live act-gov integration.
+
+### Added
+
+- **`Helpers::Pages::OozeHandlers`** — native re-expression of `OozeSamples::Helpers::OozeHandlers`.
+  `merge_values(origin, append, type:, delimiter:)` dispatches on the GraphQL DataField TYPE STRING
+  (`PlainText`/`RichText` → newline; `Select`/`CrossReference`/`People`/`Checklist`/`ActionsList`/
+  `File`/`ImageGallery`/`Geo`/`Law` → delimiter join; `Date`/`Number`/`Gauge` → keep origin) instead
+  of `Ecoportal::API::V2::Page::Component::*` classes. `merge_arrays`/`array_indexes` ported verbatim.
+  Included into `Samples::Pages::Register::Base`, which also gains `#merge_field_values(field, append)`
+  (reads the field's own `#type` + current `#value`).
+- **`Samples::Pages::Register::TargetOozesUpdateCase`** — native counterpart of
+  `OozeSamples::TargetOozesUpdateCase`, subclassing the native `Register::Base`. Reads target page ids
+  from `options[:source][:file]` (first CSV column, header dropped), batches them, previews with
+  duplicate detection + proceed prompt, fetches each via `graphql.pages.get`, dedups by id, and hands
+  each page to `process_page`. `#each_page` (register-search) is disabled here to prevent an
+  accidental org scan.
+- **`Compat::Parity`** A/B parity harness — `RunResult` (canonical KPI + normalised per-page update
+  payload snapshot), `Comparison` (KPI/page-set/payload diffs + `equivalent?` verdict + report), and
+  `Harness` (orchestrates a legacy vs native run and compares; `.record` captures a run's observables).
+  Comparison logic is pure/offline-runnable; live capture of the two runs needs a test org + creds.
+- **`Helpers::Pages::TypedFieldsPairing`** — native re-expression of
+  `OozeSamples::HelpersMigration::TypedFieldsPairing`. Pairs data fields across two page models by
+  SAME type + SAME label, in two screenings (exact label, then mild: case-insensitive a-z with
+  bracketed content removed). Groups/dispatches by the GraphQL DataField TYPE STRING
+  (`PlainText`/`Select`/`Date`/... per `DataField::TYPE_MAP`) rather than v2 snake_case component
+  types; `EXCLUDED_TYPES` = `%w[TagField Chart FrequencyRateChart]` (never-pair). Tracks unpaired
+  src/dst fields + multi-candidate sources, with `resolve`/report helpers. Legacy class untouched.
+  This is the cross-template field-pairing (migration), DISTINCT from `OozeHandlers#merge_values`
+  (value-merge of one already-paired field).
+- **`Helpers::Pages::Copying`** — native counterpart of
+  `OozeSamples::HelpersMigration::Copying`. `copy_generic_paired_fields(src, dst)` runs
+  `TypedFieldsPairing` and copies each pair's content; `copy_field_content(src, dst)` dispatches on
+  the GraphQL DataField type string (`PlainText`/`Number`/`Date`/`Gauge` → `value=`, `RichText` →
+  `content=`, `Select` → `select_option`, `CrossReference` → `page_ids=`; other types left untouched).
+  The v2 regex/JSON hooked-field mapping layer (`copy_hooked_fields`) is NOT ported (later increment).
+- **`Samples::Pages::Register::MigrationCase`** — native counterpart of
+  `OozeSamples::RegisterMigrationCase`, subclassing the native `Register::Base` and mixing in
+  `Copying`. Iterates a source register, drafts a NEW entry of `TEMPLATE_ID` (via native `Creatable`),
+  pairs the source fields to the draft's fields and copies content across, runs the unpaired /
+  multi-pair reports, and hands the draft to `#custom_processing` for finalising. Per-page persistence
+  is the native create path (not the v2 batch queue). Native-only; no OozeSamples name flipped.
+
+Template automatic build & maintenance (Phase 5): native, offline-safe orchestration on top of the
+released gem's `Diff::Deploy` / `Diff::VersionDiff` / `Builder::Template`. Additive, no case flipped.
+
+- **`Samples::Pages::Template::Deploy`** — deploy → verify → monitor loop for template (workflow)
+  changes, driven by a gem `Diff::Deploy` command batch. Dry-run is the DEFAULT; live apply is gated
+  behind an explicit `commit: true` + executor. All components are session-less and offline-runnable
+  (the apply / re-read seams are injected).
+  - `Deploy::Applier` — wraps a gem `Diff::Deploy` plan. Dry-run records the batch it WOULD send;
+    `commit: true` applies it via any `execute_workflow_commands`-shaped executor (gem `Builder::Page`
+    facade adapted by `TargetBoundExecutor`). Refuses to apply while the plan has `unsupported`
+    changes unless `allow_partial: true` — nothing is guessed.
+  - `Deploy::RecordingExecutor` — offline stand-in that records batches and (with a `mutator`) replays
+    them onto an in-memory doc, so the pre/post drift check is runnable with no API call.
+  - `Deploy::DriftReport` — compares the APPLIED delta (a pre/post self-version `Diff::VersionDiff` of
+    the re-read target) to the INTENDED delta (the source diff the batch came from) on an id-free shape
+    signature; reports `missing` (under-applied) and `unexpected` (side-effect) changes honestly.
+  - `Deploy::Verifier` — pluggable post-deploy verification. `QaVerifier` wires the `ecoportal-qa`
+    check framework through a single seam when the gem is on the load path (NOT a hard dependency);
+    otherwise `NullVerifier` keeps the loop runnable and is honest that qa was unavailable.
+  - `Deploy::SyncReadiness` — given a register subset + its active template doc, reports which entries
+    CAN sync (all REQUIRED fields present, non-empty, and correctly typed) vs not, with per-entry
+    reasons.
+  - `Deploy::Loop` — orchestrates apply → drift → verify → sync-readiness and yields an aggregate
+    `Result` (`ok?` gate + human `report`). The applied-diff builder defaults to the gem's
+    `Diff::VersionDiff` (resolved lazily) and is injectable for offline use.
+- **`Samples::Pages::Template::CsvBuild`** — CSV → template BUILD pipeline reusing the existing
+  `Template::CommandEmitter` + the released gem `Builder::Template#create(commands:)`.
+  - `CsvBuild::FormatMap` — the SINGLE, isolated place the assumed columnar format lives (column names
+    + option delimiters), mapping a CSV row to a format-agnostic `RowSpec`. ⚠ The exact ~300-template
+    CSV column format is due ~mid-July 2026 and is NOT yet confirmed — only this file (and its spec)
+    changes when the real format lands.
+  - `CsvBuild::Parser` — groups rows into a stage → section → field tree preserving first-seen order.
+  - `CsvBuild::Builder` — replays the tree onto `CommandEmitter` (same placeholder-id threading), emits
+    the ordered `WorkflowCommand` batch (select options → `addSelectFieldOption`), and stamps a hidden
+    per-section anchor field for the identity convention (hidden-field + description). Offline/dry-run
+    by default (`#commands`, `#preview`); `#create!(template_facade)` is the live path (needs creds).
+  - `Template::CommandEmitter#field` gains optional `description:`/`required:` pass-throughs (additive).
+- **HONEST LIMITATIONS / deferred:**
+  - The released gem (1.3.9) does NOT yet ship `Diff::Deploy` / `Diff::VersionDiff` (unreleased on the
+    gem's main). The deploy loop is written against those APIs but touches them only via lazy/injected
+    seams, so it loads and its specs run offline today; a live drift check needs those classes released.
+  - The released gem's `addField` input drops any key outside
+    placeholderId/fieldType/label/stageId/sectionId/column, so the `description` identity token is NOT
+    yet persisted through addField — only the hidden anchor field's presence survives. Wiring is in
+    place so identity flows end-to-end once the gem's addField gains a description key.
+  - Live deploy/apply and live template creation both need credentials + a test org (the sandbox
+    cannot reach live). qa verification is stubbed behind `QaVerifier`'s single seam until qa is pinned.
+
 ## [3.2.16] - 2026-07-02
 
 APIv2→GraphQL cutover — the OozeRedirect compat layer that runs the maintained ooze integrations

data/eco-helpers.gemspec

@@ -42,8 +42,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'docx',          '>= 0.8.0', '< 0.9'
   spec.add_dependency 'dotenv',        '~> 3'
   spec.add_dependency 'ecoportal-api',         '~> 0.10', '>= 0.10.14'
-  spec.add_dependency 'ecoportal-api-graphql', '~> 1.3',  '>= 1.3.9'
-  spec.add_dependency 'ecoportal-api-v2',      '~> 3.3',  '>= 3.3.1'
+  spec.add_dependency 'ecoportal-api-graphql', '~> 1.3',  '>= 1.3.11'
+  spec.add_dependency 'ecoportal-api-v2',      '~> 3.3',  '>= 3.3.3'
   spec.add_dependency 'ed25519',       '~> 1.2'
   spec.add_dependency 'fast_excel',    '>= 0.5.0',  '< 0.6'
   spec.add_dependency 'fuzzy_match',   '>= 2.1.0',  '< 2.2'

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

@@ -1,6 +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

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

@@ -0,0 +1,78 @@
+module Eco::API::UseCases::GraphQL::Helpers
+  module Pages
+    # Native GraphQL re-expression of OozeSamples::Helpers::Creatable.
+    #
+    # Provides the "create a new entry (page) from a template" flow used by
+    # register-processing use cases. Mirrors the v2 Creatable structure
+    # (creating_new_page -> drafting_entry -> create_entry -> create_ooze) but
+    # talks to the native GraphQL stack (`graphql.pages.get_new` / `graphql.pages.create`)
+    # and respects `simulate?` for dry-run feedback.
+    #
+    # Included via the base-type guard: it can only be mixed into the native
+    # register case (Samples::Pages::Register::Base), which supplies the
+    # `create_ooze` hook + KPI counters it drives.
+    module Creatable
+      module InstanceMethods
+        private
+
+        # Draft a page from `template_id`, let the caller fill it, then persist it.
+        # @param draft_reference [String] human-readable label for logs.
+        # @param template_id [String] the template to build the draft from.
+        # @yield [draft] the built (still unsaved) draft page to mutate.
+        # @return [String, nil] the created page id, or nil on dry-run / failure.
+        def creating_new_page(draft_reference = 'new entry', template_id:)
+          page_id = nil
+          drafting_entry(template_id) do |draft|
+            yield(draft) if block_given?
+
+            if (page_id = create_entry(draft, reference: draft_reference))
+              log(:info) { "Page '#{page_id}' created successfully -- #{draft_reference}" }
+            elsif simulate?
+              log(:info) { "Simulated launch for #{draft_reference}" }
+            end
+          end
+          page_id
+        end
+
+        # @return [Object] a draft page of `template_id` (still not saved).
+        def drafting_entry(template_id)
+          raise ArgumentError, 'Expecting block, but not given' unless block_given?
+
+          draft = graphql.pages.get_new(template_id)
+          yield(draft)
+        end
+
+        # Does the actual creation of the entry (wrapped so a per-item error does
+        # not abort the whole run).
+        # @return [String, nil] the created page id, or nil.
+        def create_entry(draft, reference: "new entry from #{draft&.template_id}")
+          with_rescue(reference) do
+            if (result = create_ooze(draft, template_id: draft.template_id))
+              return result.page_id
+            end
+          end
+        end
+      end
+
+      class << self
+        def included(base)
+          super
+
+          validate_base_type!(base)
+          base.include(InstanceMethods)
+        end
+
+        def validate_base_type!(base)
+          return super if defined?(super)
+
+          register_base = Eco::API::UseCases::GraphQL::Samples::Pages::Register::Base
+          msg  = "#{self} can only be included in #{register_base}"
+          msg << "\nCan't be included in #{base}"
+          raise LoadError, msg unless base <= register_base
+
+          true
+        end
+      end
+    end
+  end
+end