eco-helpers 3.2.14 → 3.2.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d67a16095de2e32c2c627214b0254df6d2685e0591ab6295082736e52494c4d3
-  data.tar.gz: 60835a688189d8feda9bdc6198bbdb0cfaa9e9f95e5c7521f36cedbec706c1b0
+  metadata.gz: 2803cb1dc211ef8682ebcd33e4007f4e748b5eb42f56ecbaa931b5258064ead8
+  data.tar.gz: 7c0f5f66654761ce6ee5cb37ca4eb354054161c0fc3914c37da27f7f6fce4273
 SHA512:
-  metadata.gz: 0c1ded6a88ad0c6394e96cb511fddb5c5ac29635307affc1577d5eeb210f01ad8dd78edf78e449b9bca765a8754aa31083abb72beb60746ed21741e523878e6c
-  data.tar.gz: a18f9c81c2430ba8251bdfc34e6e4e1d3da0fd3cbe4647226942469d8da1f71e00aa7e21e3162d9d89d492f98e800642c0132edc30a305515df67764c397de91
+  metadata.gz: 10235574cf1a38826f4de995d715747b65fd657e0ef4e183b04644f8e26bebb2471c4d118fbbc00eac72e174d74c72d4685c9fb49a9a3667d8320c005ef7983a
+  data.tar.gz: e9f15c9f0e9c5243c835402fe64efd1384021773d3e0c0d65fbbfe17bd10128e944932e9a8ac21501cf31025040c9fcc0b2b26b8eb70844fd631f899008c822c

data/CHANGELOG.md

@@ -2,6 +2,227 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.2.23] - 2026-09-30
+
+Security republish of 3.2.22. **Backwards-compatible; no code change**: same dependencies, same
+behaviour. Supersedes the published versions of this line, which are to be yanked.
+
+### Security
+
+- Removed customer and internal identifiers from shipped code comments and this changelog (a
+  comment listing customer organisations and their case names; internal repository names and
+  internal documentation paths). Comments and changelog only. It also carries the full-path packaging allowlist from 3.3.2, so the five internal
+  `CLAUDE.md` files that 3.2.22 packaged under `lib/` no longer ship.
+- Packaging: the three runtime JSON files are declared in `.release-smoke-allow`, and the release
+  tasks accept `release/*` maintenance branches.
+
+## [3.2.22] - 2026-08-14
+
+### Fixed
+
+- Republish of `3.2.21`: its `lib/eco/version.rb` shipped with doubled carriage returns
+  (`
+` line endings), causing a `warning: encountered  in middle of line` on every
+  load. Functionally identical otherwise; `3.2.21` will be yanked.
+
+## [3.2.21] - 2026-08-14
+
+### Fixed
+
+- Packaging-only republish of `3.2.19` with an allowlisted gemspec (backported from `3.3.0`).
+  Versions `3.2.16`-`3.2.19` shipped internal repository content (the repo's internal docs tooling,
+  `.claude/settings.json`) to rubygems.org via the old denylist `spec.files`; `3.2.19` is
+  yanked and `3.2.16`/`3.2.18` are queued for deletion by RubyGems support. `3.2.21` is the
+  identical `lib/` code packaged clean, so constraints like `'~> 3.2.0', '>= 3.2.19'` keep
+  resolving on the 3.2 line (its graphql dependency stays `~> 1.3`, satisfied by the clean
+  `1.3.16`). The version number `3.2.20` is intentionally skipped: it exists as a
+  tagged-but-deliberately-unpublished version (see the 3.3.0-era changelog corrections).
+
+## [3.2.19] - 2026-07-16
+
+A customer's `cans-upsert` reliability adoption + an ooze KPI counter fix. **Backwards-compatible.**
+Cut from the `v3.2.18` tag (not `master`, which carries the native GraphQL activity/dashboard
+readers depending on the unreleased gem `1.4.0`), so this ships needing only the published
+`ecoportal-api-graphql 1.3.14`.
+
+### Changed
+
+- **Floor `ecoportal-api-graphql` to `>= 1.3.14`** (was `>= 1.3.11`) — pulls the HttpClient
+  429/1015 resilience fix, so bulk `cans-upsert` / register-update live runs are no longer
+  aborted by a single Cloudflare edge rate-limit.
+
+### Fixed
+
+- **Ooze update KPI counters now count GraphQL updates.** `RegisterUpdateCase` tallied
+  `updated`/`failed` only when the result `is_a?(Ecoportal::API::Common::Response)`, but the
+  GraphQL compat layer returns an `Ecoportal::API::GraphQL::Compat::Response` — it duck-types
+  `success?`/`status` yet is not in that class hierarchy, so every GraphQL update was silently
+  uncounted (`Updated 0 (attempted: N)`, `Failed 0`) even when the write applied. The guard is
+  now a duck-type (`respond_to?(:success?)`); `false`/`nil` returns (dry-run / no-op) still skip.
+  **Note:** this fixes the *report* only — the updates themselves were already applying.
+
+## [3.2.18] - 2026-07-10
+
+Version-identity + regression-guard release. **No behaviour change** vs the fixed `3.2.17` build —
+this bump exists so the LocationDraft fix can be pinned/verified by version, and adds an offline
+guard so the dead-fragment class of bug can't reach production again.
+
+### Why this bump
+
+`3.2.17` shipped as **two different builds under one version**: the version was bumped to `3.2.17`
+on 2026-07-04 (`243822b9`), then the live-crash fix `352a9657` (LocationDraft dead-fragment
+convention) landed on 2026-07-05 — keeping the same `3.2.17` label. Because `3.2.17` is installed
+from git/path (unpublished), a consumer bundled in that ~26h window reports `3.2.17` yet lacks the
+fix. This crashed the **live customer** org-structure sync again on 2026-07-09 with the exact
+`uninitialized constant …Fragment::LocationDraft (NameError)`. Bumping to `3.2.18` makes the fixed
+build unambiguously identifiable: any consumer on `>= 3.2.18` provably has the fix.
+
+### Added
+
+- **Regression-guard spec for the dead-fragment convention.**
+  `spec/…/helpers/location/command/end_points/optimizations_spec.rb` scans every file under
+  `usecases/graphql/` and fails if any references a fragment via the removed `___Const__Fragment` /
+  `::Fragment::<Name>` constant convention (the exact NameError that crashed a customer sync), and asserts
+  the three Location command payload procs still route fragments through the `spread :Name` registry
+  DSL. It is a SOURCE lint, not a full offline render: rendering needs the graphlient fork's
+  `to_query_string`/`spread` DSL, but eco-helpers' own bundle resolves stock graphlient `0.8.0` (the
+  fork is pinned only in the deployment/gem bundles). If eco-helpers later pins the fork in dev/test,
+  promote this to a real render guard like the gem's `tests/validate_queries.rb`.
+
+## [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 a customer's live 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 a customer's live 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
+(toocs-coding, cans-upsert, supplier-documents) on GraphQL. Requires ecoportal-api-graphql >= 1.3.9.
+
+### Fixed / Changed
+
+- **OozeRedirect slimmed onto the base OozeSamples loop** — removed the `with_each_entry` /
+  `update_ooze` / `process_ooze` overrides that duplicated and silently bypassed the base loop
+  (KPIs, dedup, queue, `dry_run_feedback`). Fetches go through `ooze → apiv2.pages.get` and saves
+  through `update_oozes → update_ooze → apiv2.pages.update`; a captured `submit!`/`sign_off!` rides
+  along on the single `updatePage` via `Input::Page::Update.from_model` (reads the `_compat_*` flags).
+- **`dirty?`** also treats a pending `submit!`/`sign_off!` as dirty (so a submit-only page still saves).
+- **`OozeBaseCase#dry_run_feedback`** prints an affirmative `[dry-run] would create/update <ref>` line.
+- **`RegisterUpdateCase#enqueue`** accepts any duck-typed entry (`#dirty?` + `#as_update`), not just
+  v2 `Page`/`PageStage` — GraphQL compat pages queue correctly under OozeRedirect.
+
 ## [3.2.15] - 2026-05-xx
 
 ### Added

data/lib/eco/api/usecases/default/pages.rb

@@ -0,0 +1,30 @@
+module Eco
+  module API
+    class UseCases
+      class Default
+        # Namespace for CLI-integrated page use cases.
+        # These are concrete, fully functional cases exposed to all org environments.
+        #
+        # == Convention
+        # Cases here should:
+        # - Inherit from Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
+        #   (or OrgPage::Base for org-wide operations)
+        # - Be registered in the org's config/cli.rb
+        # - Be as org-agnostic as possible (accept register_id, filters via options)
+        #
+        # == Adding a new default page case
+        # 1. Create the file here: default/pages/my_case.rb
+        # 2. Inherit from the appropriate pages sample base class
+        # 3. Require it below
+        # 4. Wire CLI registration in usecases/default_cases/samples.rb or the
+        #    org's config/cli.rb
+        #
+        # == Currently
+        # No default page cases yet — add them here as common patterns emerge
+        # across org implementations.
+        module Pages
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  # Array subclass that calls the field's setter when elements are appended,
+  # ensuring GraphQL dirty-tracking fires on `fld.people_ids << value`.
+  class DirtyArray < Array
+    def initialize(field, data)
+      @field = field
+      super(Array(data))
+    end
+
+    def <<(value)
+      super
+      @field.people_ids = to_a
+      self
+    end
+
+    def push(*values)
+      super
+      @field.people_ids = to_a
+      self
+    end
+  end
+end

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

@@ -0,0 +1,241 @@
+module Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  # Applies one-time compatibility patches to v2 and GraphQL field classes.
+  # Idempotent — safe to call multiple times (first call does the work, rest no-op).
+  #
+  # After apply!:
+  #   1. V2 type classes recognise GraphQL instances in case/when dispatch
+  #   2. GraphQL field classes respond to the v2 field interface
+  module FieldPatches
+    @applied = false
+
+    V2_TO_GQL = {
+      'PlainTextField'   => 'PlainText',
+      'NumberField'      => 'Number',
+      'SelectionField'   => 'Select',
+      'PeopleField'      => 'People',
+      'ReferenceField'   => 'CrossReference'
+    }.freeze
+
+    def self.apply!
+      return if @applied
+
+      # eco-helpers lazy-requires the gem only when session.api(version: :graphql) is first
+      # used (runtime). apply! runs at OozeRedirect.included (boot) — BEFORE that — so the
+      # gem classes aren't loaded yet: every safe_const below would return nil, the patches
+      # would silently no-op, and @applied would latch with nothing patched. Force the gem
+      # load now so all the GraphQL consts resolve.
+      require 'ecoportal/api-graphql'
+
+      @applied = true
+      patch_v2_type_dispatch!
+      patch_graphql_base_field!
+      patch_graphql_people!
+      patch_graphql_cross_reference!
+      patch_graphql_select!
+    end
+
+    # --- 1. V2 type dispatch -------------------------------------------------
+
+    # Reopen each V2 field class so that `===` also returns true for the
+    # equivalent GraphQL field type.  This makes existing `case/when` dispatch
+    # work transparently without touching the end scripts.
+    def self.patch_v2_type_dispatch!
+      V2_TO_GQL.each do |v2_type, gql_type|
+        v2_klass  = safe_const("Ecoportal::API::V2::Page::Component::#{v2_type}")
+        gql_klass = safe_const("Ecoportal::API::GraphQL::Base::Page::DataField::#{gql_type}")
+        next unless v2_klass && gql_klass
+
+        gql_ref = gql_klass   # capture for the closures
+        v2_ref  = v2_klass
+
+        # case/when dispatch: `V2Class === graphql_instance`.
+        v2_klass.define_singleton_method(:===) do |obj|
+          super(obj) || obj.is_a?(gql_ref)
+        end
+
+        # is_a?/kind_of? guards: `graphql_instance.is_a?(V2Class)` — scripts use both the
+        # case/when form AND explicit is_a? guards (e.g. cans update_select). === alone
+        # doesn't cover is_a?, so make the GraphQL field recognise its v2 counterpart too.
+        gql_klass.prepend(Module.new do
+          define_method(:is_a?)    { |klass| klass == v2_ref || super(klass) }
+          define_method(:kind_of?) { |klass| klass == v2_ref || super(klass) }
+        end)
+      end
+    end
+
+    # --- 2. GraphQL base field: submit! + ooze stub --------------------------
+
+    def self.patch_graphql_base_field!
+      base = safe_const('Ecoportal::API::GraphQL::Base::Page::DataField')
+      return unless base
+
+      # submit! — stores a pending submit flag consumed by the infrastructure
+      base.class_eval do
+        def _compat_submit_pending?
+          @_v2_compat_submit_pending
+        end
+      end
+
+      # BasePage submit! — called as target.submit!(force: true) in scripts
+      page_base = safe_const('Ecoportal::API::GraphQL::Interface::BasePage')
+      return unless page_base
+
+      page_base.class_eval do
+        # v2-compat stage SUBMIT. Scripts call `target.submit!` (optionally pinning a
+        # stage via `submit!(stage_id:)`). Captures the intent; OozeRedirect#process_ooze
+        # consumes it → `graphql.pages.update(submit: true)`. Submitting completes the
+        # stage's fill-in task (the server requires all visible, non-hidden required
+        # fields to be filled). If the stage also has a review task configured, it then
+        # awaits a SEPARATE `sign_off!`. submit! does NOT sign off.
+        #
+        # `submit!(force: true)` maps to completePageTask.forcedComplete: true — the
+        # backend then SKIPS the empty visible-required-field check. This is admin/
+        # superuser-only server-side; the integration's service user must hold that
+        # permission (it did under APIv2, so the same account carries it on GraphQL).
+        def submit!(force: false, stage_id: nil)
+          @_v2_compat_submit_pending  = true
+          @_v2_compat_submit_stage_id = stage_id
+          @_v2_compat_submit_force    = force ? true : false
+        end
+
+        # v2-compat stage SIGN-OFF. Scripts call `target.sign_off!` (optionally
+        # `sign_off!(stage_id:)`). Per the platform model the stage tasks are sequential
+        # (fill-in → review): signing off a stage that has NOT been submitted yet also
+        # submits it — a permitted user may submit + sign off in one go (also the page-
+        # creation path). process_ooze realises this as
+        # `updatePage(submit: true, completePageTask { signOff: true })`, which the
+        # backend treats as submit + inline review approval, advancing the stage.
+        def sign_off!(stage_id: nil)
+          @_v2_compat_sign_off_pending  = true
+          @_v2_compat_sign_off_stage_id = stage_id
+        end
+
+        def _compat_submit?
+          @_v2_compat_submit_pending
+        end
+
+        def _compat_submit_stage_id
+          @_v2_compat_submit_stage_id
+        end
+
+        def _compat_submit_force?
+          @_v2_compat_submit_force ? true : false
+        end
+
+        def _compat_sign_off?
+          @_v2_compat_sign_off_pending
+        end
+
+        def _compat_sign_off_stage_id
+          @_v2_compat_sign_off_stage_id
+        end
+      end
+    end
+
+    # --- 3. People field -----------------------------------------------------
+
+    def self.patch_graphql_people!
+      klass = safe_const('Ecoportal::API::GraphQL::Base::Page::DataField::People')
+      return unless klass
+
+      klass.prepend(Module.new do
+        # Return a DirtyArray so fld.people_ids << value triggers dirty tracking
+        def people_ids
+          DirtyArray.new(self, Array(super))
+        end
+
+        # Stub: back-reference used in v2 warning messages
+        def ooze
+          Struct.new(:uid, :name, :id).new('(graphql)', label, id)
+        end
+      end)
+    end
+
+    # --- 4. CrossReference (v2 ReferenceField) field -------------------------
+
+    def self.patch_graphql_cross_reference!
+      klass = safe_const('Ecoportal::API::GraphQL::Base::Page::DataField::CrossReference')
+      return unless klass
+
+      klass.prepend(Module.new do
+        # v2 compat: fld.reference_ids → fld.page_ids
+        def reference_ids
+          page_ids || []
+        end
+
+        # v2 compat: fld.add(ep_id)
+        def add(ep_id)
+          return if ep_id.nil?
+
+          self.page_ids = (page_ids || []) + [ep_id] unless (page_ids || []).include?(ep_id)
+        end
+
+        # v2 compat: fld.clear
+        def clear
+          self.page_ids = []
+        end
+
+        def ooze
+          Struct.new(:uid, :name, :id).new('(graphql)', label, id)
+        end
+      end)
+    end
+
+    # --- 5. Select field -----------------------------------------------------
+
+    OptionStruct = Struct.new(:id, :name, :value, :selected)
+
+    def self.patch_graphql_select!
+      klass = safe_const('Ecoportal::API::GraphQL::Base::Page::DataField::Select')
+      return unless klass
+
+      klass.prepend(Module.new do
+        # v2 compat: fld.options → array of OptionStructs (respond to .name, .value)
+        def options
+          Array(doc['options'] || []).map do |opt|
+            FieldPatches::OptionStruct.new(opt['id'], opt['name'], opt['value'], opt['selected'])
+          end
+        end
+
+        # v2 compat: fld.select(value, by_name: false) or fld.select(name, by_name: true)
+        def select(val, by_name: false)
+          select_option(val.to_s)
+          self
+        end
+
+        # v2 compat: fld.deselect(value) — deselect one specific option
+        def deselect(val)
+          (doc['options'] || []).each do |opt|
+            target = val.to_s
+            if [opt['id'], opt['name'], opt['value']].map(&:to_s).include?(target)
+              opt['selected'] = false
+            end
+          end
+          # No explicit dirty call: mutating doc['options'] in place is picked up
+          # by DataField's LeafDiffService diff (same as native select_option /
+          # clear_selection). There is no mark_dirty! method on the field.
+          self
+        end
+
+        # v2 compat: fld.values — array of selected option values
+        def values
+          (doc['options'] || []).select { |opt| opt['selected'] }.map { |opt| opt['value'] }
+        end
+
+        def ooze
+          Struct.new(:uid, :name, :id).new('(graphql)', label, id)
+        end
+      end)
+    end
+
+    def self.safe_const(path)
+      path.split('::').reduce(Object) { |mod, c| mod.const_get(c) }
+    rescue NameError
+      nil
+    end
+
+    private_class_method :patch_v2_type_dispatch!, :patch_graphql_base_field!,
+                         :patch_graphql_people!, :patch_graphql_cross_reference!,
+                         :patch_graphql_select!, :safe_const
+  end
+end

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

@@ -0,0 +1,73 @@
+module Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  # Extends OozeRedirect with Force / binding support via the GraphQL
+  # executeWorkflowCommands mutation.
+  #
+  # Automatically included by OozeRedirect when the ForceFields fragment is
+  # available in the loaded gem version.  No additional include is needed in
+  # end scripts — the same single include covers forces too:
+  #
+  #   include Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  #
+  # ## What ForceCompat adds
+  #
+  # 1. Override `with_each_entry` to fetch pages via Query::PageWithForces,
+  #    which includes forces in the GraphQL response.
+  # 2. Override `process_ooze` to call save_force_changes! after the script
+  #    runs, executing any accumulated force commands via executeWorkflowCommands.
+  #
+  # ## Accumulated commands
+  #
+  # Scripts interact with forces exactly as in v2:
+  #   force.custom_script = new_script       # queues editForce
+  #   force.bindings.add(field, name: 'n')   # queues addBinding
+  #   force.bindings.delete!(binding)        # queues removeBinding
+  #
+  # After process_ooze returns, ForceCompat collects all pending commands from
+  # all forces on the page and submits them in one executeWorkflowCommands call.
+  module ForceCompat
+    module Infrastructure
+      # Fetch pages with forces included in the GraphQL response.
+      def with_each_entry
+        warn_once(:force_fetch, 'ForceCompat: fetching pages with forces (Query::PageWithForces)')
+        target_ids.each do |page_id|
+          @target = Ecoportal::API::GraphQL::Query::PageWithForces.new(graphql.client).query(id: page_id)
+          if @target
+            yield
+          else
+            log(:warn) { "[ForceCompat] Could not fetch page #{page_id}" }
+          end
+        end
+      end
+
+      # After the script's process_ooze runs, submit all accumulated force commands.
+      def process_ooze
+        super
+        save_force_changes!
+      end
+
+      private
+
+      def save_force_changes!
+        return unless target.respond_to?(:forces)
+
+        force_col = target.forces
+        return unless force_col.dirty?
+
+        commands = force_col.pending_commands
+        return if commands.empty?
+
+        warn_once(:force_save, "ForceCompat: executing #{commands.size} force command(s) via executeWorkflowCommands")
+        return if simulate?
+
+        response = graphql.page.execute_force_commands(
+          id:        target.id,
+          patch_ver: target.patchVer.to_i,
+          commands:  commands
+        )
+        if response.respond_to?(:error?) && response.error?
+          log(:error) { "[ForceCompat] executeWorkflowCommands failed for page #{target.id}: #{response.body}" }
+        end
+      end
+    end
+  end
+end