ecoportal-api-graphql 1.3.9 → 1.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c1990322b8462a243436be2fbd9b7194512fa2ce5222a1fa5d601e248a67e4f
-  data.tar.gz: 5ed9647580308227e46a57f00fd29db20603dc66f221167630205a9fffe94ae4
+  metadata.gz: 180d0e0ea70c7fb3462ae6bdec6ef78d1480c97be0861bec6e3e4bbb4abba751
+  data.tar.gz: e2733075993edee570ef5762fe06cdaac035609e313f583b43753a4da21f0fd3
 SHA512:
-  metadata.gz: 6bd2a2fc3852bfa39f5923f0fa2a5b1a63a0fc639454b9d15ea8bbdee8276aa1a2fe7b3ddc625687a9d99e8fcb3497c7760c675390782b518a2b0a35eb9edf76
-  data.tar.gz: 01bbe1985ea4569504d703fe2ed9a93d06783e96c6e1accf9159d1e9973cf2a5cf5930c23a2d73b9eb5d79ccc00f58bd6ad6bb6ef5db7ca3686673ea5a0f0410
+  metadata.gz: e05ae227d2cc97f91c250b74c6e831cbec0f9c9f8822d0bfdebacccfbe519cf229a48f2b9222623faf1c1ff2622ac2e7c1538e0036fa4494cb7a3e9082ba6f51
+  data.tar.gz: ed6a82e38512fee2375a0bd880c1c721cee1d28597055cbeda9117a454d59f7d0a6b8bfdb1cb43fbe66fa18860a7508f426fb982ac0035d01b26140e789b1ecd

data/.ai-assistance/projects/TODO.md

@@ -2,6 +2,27 @@
 
 ## Pending
 
+- [ ] **⏰ CI: query-validation step (DUE by 2026-07-17 — within 2 weeks of 2026-07-03)** — wire
+  `tests/validate_queries.rb` into CI so the whole class of GraphQL selection bugs fails *before*
+  release, not in a client runner. **Use a FRESHLY-introspected schema** (do NOT commit the 6.3MB
+  dump — it goes stale); fail the build only on the two structural classes ("field must have
+  selections" / "selections can't be made on scalars"). Motivated by the 2026-07-03 v1.3.10 hotfix
+  (LocationStructure `updatedAt`/`createdAt`) — those queries had no spec and first broke in prod.
+  Also: fix the 3 flagged union findings — **TRIAGED 2026-07-03: all THREE are REAL bugs** (verified
+  by rendering the assembled docs + re-validating fixes; not harness/dump artifacts). Each selects
+  fields directly on a union (invalid GraphQL) — wrap in the members' shared interface:
+    - `Query::PageWithForces` (page_with_forces.rb:33-35): bare `forces` on `PageUnion` →
+      `... on BasePageInterface { forces { ...ForceFields } }`. ALSO `fragment ForceFields`
+      (fragment/force.rb:15,20) selects `id` on `DataFieldBinding`/`SectionBinding` which have NO `id`
+      (only name/reference/referenceId) → drop `id` (or use `referenceId`).
+    - `Query::PagesWorkflowCommands` (pages_workflow_commands.rb:33-37): bare `workflow` on `PageUnion`
+      → `... on BasePageInterface { workflow { ... } }`. (The "unused variable" errors were an
+      artifact — a validator cascade from the union error; no action on the vars.)
+    - `Query::RegisterPresetViews` (register_preset_views.rb:71): bare `{id key name weight}` on
+      `FieldConfigurationUnion` → `... on FieldConfigurationInterface { id key name weight }`.
+  None of these 3 queries have specs — add render/validation specs alongside the fixes. These are
+  latent (not the users-sync incident); PageWithForces is WIP. Ship as a follow-up patch (1.3.11).
+
 - [x] **Builder::Register** — `createRegister`, `updateRegister`, `destroyRegister` mutations.
   `Base::Register`, `Model::Register`, `Input::Register::Create/Update`, `Payload::Register`.
   `Builder::Register` with `create`, `update`, `destroy`, and `preset_view` sub-builder.

data/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.10] - 2026-07-03
+
+Hotfix (backwards-compatible). Resolves a live failure on the Turners & Growers users sync.
+
+### Fixed
+
+- **LocationStructure query — `updatedAt` bare selection** → `Field must have selections (field
+  'updatedAt' returns DateTime but has no selections)`. `LocationStructureType.updatedAt` returns the
+  `DateTime` object (`{ dateTime, timeZone }`), so it must be selected with sub-fields. Fixed in
+  `Query::LocationStructure` and `Query::LocationStructure::Draft` (now `updatedAt { dateTime timeZone }`).
+  The plural `Query::LocationStructures` does not select it and was unaffected.
+  - **Root cause:** the bare selection has existed since 2023 (v0.3.x) but was **never exercised** —
+    no spec covered these queries, and the tagtree/users-sync path only began fetching the location
+    structure via GraphQL (rather than APIv2) as of the cutover, so it first ran in production.
+  - **Regression guard added:** `spec/.../query/location_structure_spec.rb` renders the query blocks
+    offline and asserts `updatedAt` carries `{ dateTime timeZone }` — this would have failed in CI.
+- **LocationDraft fragment — `createdAt` over-selection** (found by the full audit below): selected
+  `createdAt { dateTime }`, but `Draft.createdAt` is an `ISO8601DateTime` **scalar** → would throw
+  `Selections can't be made on scalars` whenever the location-structure **draft** query runs. Now bare
+  `createdAt`. Guarded by the same spec.
+
+### Added
+
+- **`tests/validate_queries.rb`** — offline audit: renders every gem query (auth stubbed, no network),
+  assembles its fragments, and validates the full document against a schema introspection JSON. Flags
+  the whole bug class — object fields selected bare ("must have selections") and scalars over-selected
+  ("selections can't be made on scalars"). A full run confirmed these two location fixes are the ONLY
+  such issues across all 17 query classes (contractors, actions, pages, register, templates: clean).
+
 ## [1.3.9] - 2026-07-02
 
 APIv2→GraphQL cutover hardening (backwards-compatible). Live-validated on the maintained ooze

data/docs/worklog.md

@@ -8,6 +8,135 @@ This file tracks cross-project session state and the overall repo status.
 
 ---
 
+## ▶ SESSION 2026-07-03 (cont.) — Template self-version diff + genome finding + domain capture
+
+**Built `Ecoportal::API::GraphQL::Diff::VersionDiff`** (gem branch `feature/template-version-diff`,
+commit `19c1dea`, 8 specs, rubocop clean): two SAME-object snapshots (ids retained) → exact structural
+changelog (added/removed/changed/moved for stages/sections/fields[label,type,section-move]/options
+[label,weight]). `Diff::Change` is command-ready. This is a **shared gem capability** (admin/
+troubleshooting/integration/QA), not QA-only — per Oscar's clarification that these tools are the
+epicenter of admin+troubleshooting automation.
+
+**KEY FINDING — corrected a wrong doc claim:** `genomeSignature: String` **IS exposed** in the live
+GraphQL schema on `DataFieldsInterface` + every data-field type (verified in the schema dump). The old
+`graphql_domain_knowledge.md` claim "NOT exploitable" was wrong — corrected. Real gap: our gem doesn't
+REQUEST it (add to the data-field fragment). Genome stays a strong-but-fallible pairing signal.
+
+**Comprehensive harvestable knowledge doc:** `.ai-assistance/code/template_diff_pairing_domain.md` —
+captures Oscar's full brain-dump (UAT→PROD regression modes, no-stable-identity Mongo obstacle,
+self-version vs cross-object diff, genome verified facts + 6 failure modes, data-in-fields principle,
+equivalence-matching reframe + learning ledger, diff MODALITIES, layering, pipeline, Product context)
+so it never needs re-explaining and ep-ai-standards can harvest it. New project `template-diff-deploy`
+(INTENT+TODO). Confirmed with Oscar: equivalence reframe, self-version-first, ledger as first-class.
+
+**NEXT (template-diff-deploy):** add `genomeSignature` to fragment; `Change`→WorkflowCommands; pairing
+engine + ledger (eco-helpers, reuse `TypedFieldsPairing`); diff modalities; deploy+verify+monitor. Also
+tighten ecoportal-qa to use the gem's page-model (drop its own TemplateModel).
+
+---
+
+## ▶ SESSION 2026-07-03 — NEW tool: ecoportal-qa (QA-as-CI/CD, Phases 1–2 built, Phase 3 scoped)
+
+**Phase 3 SCOPED (docs only, branch `feature/qa-services-delivery-project`):** Jira adapter design in
+`qa-services-delivery/PHASE3-SCOPE.md` — the Jira channel is *just another consumer of the canonical
+Result* (no runner/DSL changes); `Jira::{Client,RestClient,McpClient,DryRunClient,Publisher}`;
+human-gated (report-only default, explicit `--transition`, never auto); redact-before-post + idempotent
+comments + audit. Decision (pending Oscar): interface + **REST-first**, MCP later (CI endgame likely
+lacks MCP). Sub-phase **3a (DryRunClient + Publisher) is unblocked** and can start before creds; 3b/3c
+need Jira project + token. Also added **`ROADMAP.md`** — north-star narrative (one Result → many
+channels; P1–P5 capability ladder; how each rung changes the human's day) written to make the
+vision→execution path legible for Oscar. Build blocked on 4 open Qs (Jira project/statuses, REST-vs-MCP,
+verdict field, where check-sets live).
+
+**Phase 2 done (branch `feature/phase-2`, commit `22cc865`, 31 specs green, rubocop clean):**
+CSV + HTML reporters (JSON/Text refactored to render from the canonical hash); `Redactor` PII scrub
+(preserves verdict/counts); `exe/ecoportal-qa` CLI (`run --source fixture:PATH|graphql:ID
+--format text|json|csv|html [--redact]`, exit code = verdict for CI); richer checks — negative
+assertions (stage/section/field absent), `label_pattern` regex, `field_count` (exact/`{min,max}`),
+`fields_in_order`/`sections_in_order`, select `option_weights`, top-level force presence/binding
+(skip when not captured). Synthetic `sample_template_page.json` fixture exercises them offline.
+**Only remaining Phase-2 item: live capture of `6a3fa5b8…622b` — BLOCKED on sandbox creds.**
+
+---
+
+New standalone repo **`ecoportal-qa`** (`C:\ruby_scripts\git\ecoportal-qa`, git-init'd, commit
+`1a62031`, v0.0.1) for the **Services Delivery QA team** who review **org config/template changes**
+against Jira tickets. **QA-as-CI/CD:** QA authors declarative check-sets (YAML DSL) → Ruby compiler →
+runnable checks → read-only runner → canonical Result JSON → reporting/Jira/monitoring.
+
+- Phase 1 built + green: `DSL::CheckSet`, `Compiler`, `TemplateModel`, `Source::{Fixture,Graphql}`
+  (GraphqlSource lazy/read-only), `Runner`, `Result` (verdict + honest `:skip`), `Reporters::{Json,Text}`.
+  Proven vs the real `toocs_coding_page.json` snapshot (7 pass / 2 fail / 3 skip). 11 specs, rubocop clean.
+  Core has NO runtime gem deps (doc-based) → offline-runnable.
+- **ep-ai-standards question resolved:** standards live in ep-ai-standards; implementations live with
+  their deps. `ecoportal-qa` is its own repo but ships a `.ai-assistance/` conformance stub
+  (`conformance.json`) so ep-ai-standards discovers/governs it without owning the code.
+- Project docs on gem branch **`feature/qa-services-delivery-project`** (UNMERGED):
+  `.ai-assistance/projects/qa-services-delivery/{INTENT,DECISIONS,TODO}.md`.
+- Drivers: safety/privacy/simplicity/delegation-to-QA/monitoring/reporting/governance, Ruby, human-in-loop.
+- Roadmap: P2 CSV/HTML reporters + more checks + capture `6a3fa5b8…622b`; P3 Jira adapter (human-gated,
+  MCP vs REST TBD); P4 CI-as-code "ticket as pipeline"; P5 opt-in governed auto-approve.
+
+**Merge note:** `ecoportal-qa` is a fresh standalone repo (no default-branch merge needed — it IS the
+main line there). Only the gem's `feature/qa-services-delivery-project` docs branch awaits merge to main.
+
+---
+
+## ▶ SESSION 2026-07-02 — Template pipeline + ooze-native foundations (4 branches, unmerged)
+
+Post-cutover, picked up **two** parallel threads at Oscar's direction: (3) ooze → native GraphQL
+migration — **native classes ONLY, no delegation flip yet** — and (4) the template-editing (CSV)
+pipeline. Grounded both against live code via two parallel Explore surveys before writing. All work
+is on feature branches, **green + rubocop-clean, unmerged**, pending Oscar's review + the merge plan
+below. Nothing touches `main`/`master` yet; all additions are pure/non-breaking (no case flipped, no
+shim removed, no existing API changed).
+
+**Key findings (corrected the design docs):**
+- A **template IS a page** — `Query::Templates` returns PageUnion; structure reads via the page
+  model. `Builder::Template` (create/update with `commands:`) + `executeWorkflowCommands` already
+  exist. So build-from-scratch is unblocked; only workflow-config *diff* waits on the partial
+  `PagesWorkflow.stages` read model.
+- **`placeholderId` is the id-threading primitive** — commands reference not-yet-created nodes
+  intra-batch by client-chosen placeholder; simpler than the location engine's `newId` remap.
+- **`build_commands` is non-idempotent** for key-renaming commands (addSelectFieldOption:
+  data_field_id→dataFieldId). Emitter output is FINAL built form, straight to the mutation.
+- Ooze: first-wave cutover cases (RegisterUpdateCase/TargetOozesUpdateCase) are **force-free**
+  (migratable now); forces live only in downstream training scripts. Native `Pages::Page::Base`
+  already gives the loop skeleton to build on.
+
+**Branches (all green, rubocop clean, UNMERGED):**
+| Repo | Branch | Contents | Base |
+|---|---|---|---|
+| gem | `feature/template-editing-pipeline` | `tests/dump_template_model.rb`, WorkflowCommand serialization spec (10 ex), `template-maintenance/PHASE0-FINDINGS.md` | main @03799f5 |
+| gem | `feature/ooze-native-phase0` | `ooze-graphql-native-migration/INVENTORY.md` + TODO scope note | main @03799f5 |
+| eco-helpers | `feature/ooze-graphql-native-migration` | `graphql/helpers/pages/{shortcuts,filters,rescuable}` + specs (37 ex) | master @5b9d7c07 |
+| eco-helpers | `feature/template-editing-pipeline` | `graphql/samples/pages/template/{command_emitter,base}` + spec (9 ex) | master @5b9d7c07 |
+
+**STRATEGIC MERGE PLAN (for Oscar to action):**
+1. **Gem first** (no cross-repo dep): merge `feature/ooze-native-phase0` (docs-only) then
+   `feature/template-editing-pipeline` into `main`. Independent; either order. No release bump
+   needed (tool + specs + docs; patch-level if tagging).
+2. **eco-helpers next** (depends only on the *released* gem v1.3.9, which ships the WorkflowCommand
+   contract — no gem changes are required by either eco-helpers branch): merge
+   `feature/ooze-graphql-native-migration` (pure helper additions) then
+   `feature/template-editing-pipeline` (samples additions) into `master`. Independent of each other.
+3. **Order rationale:** gem branches carry no runtime coupling to eco-helpers; eco-helpers branches
+   only reference the *already-released* gem constant `Input::WorkflowCommand` at runtime. So there
+   is **no hard merge-order dependency** — the split is by repo, and everything is additive.
+4. **Do NOT** merge as a case flip / shim removal — those stay `[ ]` in the ooze TODO until parity
+   is proven (unchanged by this session).
+
+**★ NEXT SESSION:**
+- Template Phase 2/3: extend the emitter (editStage/editFieldConfiguration/gauge stops), then the
+  **sandbox live characterization** — run `dump_template_model.rb` on `6a3fa5b8…622b`, replay via
+  Template::Base, assert structure-equivalence. Needs a sandbox org + creds (Open Q #1).
+- Ooze Phase 1/2: re-express `OozeHandlers#merge_values` + native `Creatable` against GraphQL
+  data-field types; then native `Register::Base` on top of `Pages::Page::Base`; A/B parity harness.
+- Still open from prior: FARMERS/Travis support (F1 simulate-noop, F2 stale-patchVer) — locate
+  `FARMERS_GRAPHQL_HANDOVER.md` (api-deprecation branch, likely training repo).
+
+---
+
 ## ▶ DEEP REVIEW (2026-06-30 late) — pre-live audit of TOOCS + CANS; 3 more fixes
 
 Exhaustive audit (4 parallel sub-investigations) of both prod dry-runs before going live.

data/lib/ecoportal/api/graphql/fragment/location_draft.rb

@@ -1,53 +1,53 @@
-module Ecoportal
-  module API
-    class GraphQL
-      class Fragment
-        fragment :LocationDraft, <<~GRAPHQL
-          fragment LocationDraft on Draft {
-            id
-            name
-            notes
-            committed
-            createdAt { dateTime }
-            ok
-            conflictingIds
-            results {
-              ok
-              command {
-                id
-                state
-                __typename
-                ... on LocationInsertCommand    {
-                  nodeId name parentId insertBefore classificationIds
-                }
-                ... on LocationUpdateCommand    {
-                  nodeId newId
-                  newName: name
-                  newClassificationIds: classificationIds
-                }
-                ... on LocationArchiveCommand   { nodeId }
-                ... on LocationUnarchiveCommand { nodeId }
-                ... on LocationMoveCommand      { nodeId parentId insertBefore }
-                ... on LocationReorderCommand   { parentId orderedIds }
-              }
-              error {
-                message
-                conflictingIds
-                validationErrors {
-                  property
-                  error
-                  message
-                }
-              }
-            }
-            commands {
-              id
-              state
-              __typename
-            }
-          }
-        GRAPHQL
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :LocationDraft, <<~GRAPHQL
+          fragment LocationDraft on Draft {
+            id
+            name
+            notes
+            committed
+            createdAt
+            ok
+            conflictingIds
+            results {
+              ok
+              command {
+                id
+                state
+                __typename
+                ... on LocationInsertCommand    {
+                  nodeId name parentId insertBefore classificationIds
+                }
+                ... on LocationUpdateCommand    {
+                  nodeId newId
+                  newName: name
+                  newClassificationIds: classificationIds
+                }
+                ... on LocationArchiveCommand   { nodeId }
+                ... on LocationUnarchiveCommand { nodeId }
+                ... on LocationMoveCommand      { nodeId parentId insertBefore }
+                ... on LocationReorderCommand   { parentId orderedIds }
+              }
+              error {
+                message
+                conflictingIds
+                validationErrors {
+                  property
+                  error
+                  message
+                }
+              }
+            }
+            commands {
+              id
+              state
+              __typename
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/query/location_structure/draft.rb

@@ -1,62 +1,62 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        class LocationStructure
-          class Draft < Logic::Query
-            accepted_params :id
-            accepted_params :structureId
-            accepted_params :includeArchivedNodes, default: true
-
-            field_name :draft
-
-            class_resolver :item_class, Model::LocationStructure::Draft
-
-            private
-
-            def basic_block(&block)
-              final_block = block || default_query_block
-              proc {
-                query(
-                  id:                   :id!,
-                  structureId:          :id!,
-                  includeArchivedNodes: :boolean
-                ) {
-                  currentOrganization {
-                    locations {
-                      structure(
-                        id: :structureId
-                      ) {
-                        id
-                        name
-                        archived
-                        updatedAt
-                        draft(
-                          id: :id,
-                          &final_block
-                        )
-                      }
-                    }
-                  }
-                }
-              }
-            end
-
-            def default_query_block
-              proc {
-                spread :LocationDraft
-                structure {
-                  nodes(
-                    includeArchived: :includeArchivedNodes
-                  ) {
-                    spread :LocationNode
-                  }
-                }
-              }
-            end
-          end
-        end
-      end # Query
-    end # GraphQL
-  end # API
-end # Ecoportal
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        class LocationStructure
+          class Draft < Logic::Query
+            accepted_params :id
+            accepted_params :structureId
+            accepted_params :includeArchivedNodes, default: true
+
+            field_name :draft
+
+            class_resolver :item_class, Model::LocationStructure::Draft
+
+            private
+
+            def basic_block(&block)
+              final_block = block || default_query_block
+              proc {
+                query(
+                  id:                   :id!,
+                  structureId:          :id!,
+                  includeArchivedNodes: :boolean
+                ) {
+                  currentOrganization {
+                    locations {
+                      structure(
+                        id: :structureId
+                      ) {
+                        id
+                        name
+                        archived
+                        updatedAt { dateTime timeZone }
+                        draft(
+                          id: :id,
+                          &final_block
+                        )
+                      }
+                    }
+                  }
+                }
+              }
+            end
+
+            def default_query_block
+              proc {
+                spread :LocationDraft
+                structure {
+                  nodes(
+                    includeArchived: :includeArchivedNodes
+                  ) {
+                    spread :LocationNode
+                  }
+                }
+              }
+            end
+          end
+        end
+      end # Query
+    end # GraphQL
+  end # API
+end # Ecoportal

data/lib/ecoportal/api/graphql/query/location_structure.rb

@@ -1,61 +1,61 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        class LocationStructure < Logic::Query
-          accepted_params :id
-          accepted_params :includeArchivedNodes, default: true
-
-          field_name :structure
-
-          class_resolver :item_class, Model::LocationStructure
-
-          private
-
-          def basic_block(&block)
-            final_block = block || default_query_block
-            proc {
-              query(
-                id:                   :id!,
-                includeArchivedNodes: :boolean
-              ) {
-                currentOrganization {
-                  locations {
-                    structure(id: :id, &final_block)
-                  }
-                }
-              }
-            }
-          end
-
-          # At the moment it always retrieves archived nodes!!
-          # @note this is on purpose, as via API
-          #   there isn't much sense in not including archived nodes.
-          def default_query_block
-            proc {
-              id
-              name
-              archived
-              weight
-              updatedAt
-              visitorManagementEnabled
-              nodes(
-                includeArchived: :includeArchivedNodes
-              ) {
-                spread :LocationNode
-              }
-              drafts {
-                id
-                createdAt
-                name
-                notes
-              }
-            }
-          end
-        end
-      end
-    end
-  end
-end
-
-require_relative 'location_structure/draft'
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        class LocationStructure < Logic::Query
+          accepted_params :id
+          accepted_params :includeArchivedNodes, default: true
+
+          field_name :structure
+
+          class_resolver :item_class, Model::LocationStructure
+
+          private
+
+          def basic_block(&block)
+            final_block = block || default_query_block
+            proc {
+              query(
+                id:                   :id!,
+                includeArchivedNodes: :boolean
+              ) {
+                currentOrganization {
+                  locations {
+                    structure(id: :id, &final_block)
+                  }
+                }
+              }
+            }
+          end
+
+          # At the moment it always retrieves archived nodes!!
+          # @note this is on purpose, as via API
+          #   there isn't much sense in not including archived nodes.
+          def default_query_block
+            proc {
+              id
+              name
+              archived
+              weight
+              updatedAt { dateTime timeZone }
+              visitorManagementEnabled
+              nodes(
+                includeArchived: :includeArchivedNodes
+              ) {
+                spread :LocationNode
+              }
+              drafts {
+                id
+                createdAt
+                name
+                notes
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end
+
+require_relative 'location_structure/draft'

data/lib/ecoportal/api/graphql.rb

@@ -1,138 +1,138 @@
-module Ecoportal
-  module API
-    # @attr_reader client [Common::GraphQL::Client] a client object that holds the configuration of the api connection.
-    # @attr_reader logger [Logger] the logger.
-    class GraphQL
-      include Ecoportal::API::Common::GraphQL::ClassHelpers
-
-      class_resolver :client_class, Ecoportal::API::Common::GraphQL::Client
-
-      attr_reader :client, :fragments
-
-      # Creates a `GraphQL` object to interact with the ecoPortal `GraphQL API`.
-      # @param org_id [String] the id of the target organization.
-      #    It defaults to the environmental variable `ORGANIZATION_ID`, if defined
-      # @param logger [Logger] an object with `Logger` interface to generate logs.
-      def initialize(email: nil, pass: nil, org_id: nil, host: "live.ecoportal.com")
-        kargs = {
-          email:     email,
-          pass:      pass,
-          host:      host,
-          org_id:    org_id,
-          no_schema: true
-        }
-
-        @client = client_class.new(**kargs)
-        @client.http_client = Ecoportal::API::Common::GraphQL::HttpClient.new(
-          email:  email,
-          pass:   pass,
-          org_id: org_id,
-          host:   host
-        )
-        @fragments = Ecoportal::API::GraphQL::Fragment.new(client)
-      end
-
-      def currentOrganizationClass
-        API::GraphQL::Model::Organization.tap do |org_class|
-          org_class.client = client
-        end
-      end
-
-      def currentOrganization
-        currentOrganizationClass
-      end
-
-      def createContractorEntity(input:, &block)
-        createContractorEntityMutation.query(input: input, &block)
-      end
-
-      def contractorEntity
-        Ecoportal::API::GraphQL::Builder::ContractorEntity.new(client)
-      end
-
-      # Gives a builder to use different options to modify a reporting structure
-      def locationStructure
-        Ecoportal::API::GraphQL::Builder::LocationStructure.new(client)
-      end
-
-      # Gives a builder to use different options to play with action
-      def action
-        Ecoportal::API::GraphQL::Builder::Action.new(client)
-      end
-
-      # Gives a builder to use different options to work with pages
-      def page
-        Ecoportal::API::GraphQL::Builder::Page.new(client)
-      end
-
-      # v2-compatible pages API — exposes get/get_new/create/update/get_body
-      # matching the interface eco-helpers scripts use against ecoportal-api-v2.
-      def pages
-        Compat::Pages.new(client)
-      end
-
-      # v2-compatible registers API — exposes search with cursor pagination.
-      def registers
-        Compat::Registers.new(client)
-      end
-
-      # Mutation builder for register CRUD + preset view management.
-      # Distinct from #registers (compat search layer).
-      #
-      # Usage:
-      #   api.register.create(input: { name: 'Safety', moduleType: 'form', filterTags: [] })
-      #   api.register.preset_view.list('REG_ID')
-      #   api.register.preset_view.create(input: { registerId: 'R', name: 'Active', fieldConfigs: [] })
-      def register
-        Ecoportal::API::GraphQL::Builder::Register.new(client)
-      end
-
-      # Kickstand workflow engine controls — start/stop/fail individual workflows
-      # or bulk-update a set. Internal back-end automation; not for customer scripts.
-      def kickstand
-        Builder::Kickstand.new(client)
-      end
-
-      # Template management — create/update/publish/unpublish templates and manage
-      # template information and related pages.
-      def template
-        Builder::Template.new(client)
-      end
-
-      # File upload orchestrator — get S3 credentials, upload to S3, register, poll.
-      # Returns a fileContainerId string usable in FileField/ImageGallery mutations.
-      #
-      # Usage:
-      #   id = api.file_upload.upload('/path/to/report.pdf')
-      #   page.components.get_by_name('Report').file_container_ids = [id]
-      #   api.pages.update(page)
-      def file_upload
-        Ecoportal::API::GraphQL::FileUpload::Client.new(self)
-      end
-
-      private
-
-      def createContractorEntityMutation
-        Ecoportal::API::GraphQL::Mutation::ContractorEntity::Create.new(client)
-      end
-    end
-  end
-end
-
-require_relative 'graphql/helpers'
-require_relative 'graphql/concerns'
-require_relative 'graphql/logic/base_model'
-require_relative 'graphql/error'
-require_relative 'graphql/interface'
-require_relative 'graphql/base'
-require_relative 'graphql/model'
-require_relative 'graphql/logic'
-require_relative 'graphql/connection'
-require_relative 'graphql/payload'
-require_relative 'graphql/input'
-require_relative 'graphql/fragment'
-require_relative 'graphql/query'
-require_relative 'graphql/mutation'
-require_relative 'graphql/builder'
-require_relative 'graphql/compat'
-require_relative 'graphql/file_upload'
+module Ecoportal
+  module API
+    # @attr_reader client [Common::GraphQL::Client] a client object that holds the configuration of the api connection.
+    # @attr_reader logger [Logger] the logger.
+    class GraphQL
+      include Ecoportal::API::Common::GraphQL::ClassHelpers
+
+      class_resolver :client_class, Ecoportal::API::Common::GraphQL::Client
+
+      attr_reader :client, :fragments
+
+      # Creates a `GraphQL` object to interact with the ecoPortal `GraphQL API`.
+      # @param org_id [String] the id of the target organization.
+      #    It defaults to the environmental variable `ORGANIZATION_ID`, if defined
+      # @param logger [Logger] an object with `Logger` interface to generate logs.
+      def initialize(email: nil, pass: nil, org_id: nil, host: "live.ecoportal.com")
+        kargs = {
+          email:     email,
+          pass:      pass,
+          host:      host,
+          org_id:    org_id,
+          no_schema: true
+        }
+
+        @client = client_class.new(**kargs)
+        @client.http_client = Ecoportal::API::Common::GraphQL::HttpClient.new(
+          email:  email,
+          pass:   pass,
+          org_id: org_id,
+          host:   host
+        )
+        @fragments = Ecoportal::API::GraphQL::Fragment.new(client)
+      end
+
+      def currentOrganizationClass
+        API::GraphQL::Model::Organization.tap do |org_class|
+          org_class.client = client
+        end
+      end
+
+      def currentOrganization
+        currentOrganizationClass
+      end
+
+      def createContractorEntity(input:, &block)
+        createContractorEntityMutation.query(input: input, &block)
+      end
+
+      def contractorEntity
+        Ecoportal::API::GraphQL::Builder::ContractorEntity.new(client)
+      end
+
+      # Gives a builder to use different options to modify a reporting structure
+      def locationStructure
+        Ecoportal::API::GraphQL::Builder::LocationStructure.new(client)
+      end
+
+      # Gives a builder to use different options to play with action
+      def action
+        Ecoportal::API::GraphQL::Builder::Action.new(client)
+      end
+
+      # Gives a builder to use different options to work with pages
+      def page
+        Ecoportal::API::GraphQL::Builder::Page.new(client)
+      end
+
+      # v2-compatible pages API — exposes get/get_new/create/update/get_body
+      # matching the interface eco-helpers scripts use against ecoportal-api-v2.
+      def pages
+        Compat::Pages.new(client)
+      end
+
+      # v2-compatible registers API — exposes search with cursor pagination.
+      def registers
+        Compat::Registers.new(client)
+      end
+
+      # Mutation builder for register CRUD + preset view management.
+      # Distinct from #registers (compat search layer).
+      #
+      # Usage:
+      #   api.register.create(input: { name: 'Safety', moduleType: 'form', filterTags: [] })
+      #   api.register.preset_view.list('REG_ID')
+      #   api.register.preset_view.create(input: { registerId: 'R', name: 'Active', fieldConfigs: [] })
+      def register
+        Ecoportal::API::GraphQL::Builder::Register.new(client)
+      end
+
+      # Kickstand workflow engine controls — start/stop/fail individual workflows
+      # or bulk-update a set. Internal back-end automation; not for customer scripts.
+      def kickstand
+        Builder::Kickstand.new(client)
+      end
+
+      # Template management — create/update/publish/unpublish templates and manage
+      # template information and related pages.
+      def template
+        Builder::Template.new(client)
+      end
+
+      # File upload orchestrator — get S3 credentials, upload to S3, register, poll.
+      # Returns a fileContainerId string usable in FileField/ImageGallery mutations.
+      #
+      # Usage:
+      #   id = api.file_upload.upload('/path/to/report.pdf')
+      #   page.components.get_by_name('Report').file_container_ids = [id]
+      #   api.pages.update(page)
+      def file_upload
+        Ecoportal::API::GraphQL::FileUpload::Client.new(self)
+      end
+
+      private
+
+      def createContractorEntityMutation
+        Ecoportal::API::GraphQL::Mutation::ContractorEntity::Create.new(client)
+      end
+    end
+  end
+end
+
+require_relative 'graphql/helpers'
+require_relative 'graphql/concerns'
+require_relative 'graphql/logic/base_model'
+require_relative 'graphql/error'
+require_relative 'graphql/interface'
+require_relative 'graphql/base'
+require_relative 'graphql/model'
+require_relative 'graphql/logic'
+require_relative 'graphql/connection'
+require_relative 'graphql/payload'
+require_relative 'graphql/input'
+require_relative 'graphql/fragment'
+require_relative 'graphql/query'
+require_relative 'graphql/mutation'
+require_relative 'graphql/builder'
+require_relative 'graphql/compat'
+require_relative 'graphql/file_upload'

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GRAPQL_VERSION = '1.3.9'.freeze
+    GRAPQL_VERSION = '1.3.10'.freeze
   end
 end

data/tests/validate_queries.rb

@@ -0,0 +1,105 @@
+require 'ecoportal/api-graphql'
+require 'json'
+require 'graphql'
+
+# Validate EVERY gem query against a GraphQL schema, offline — catches the whole class of
+# "field must have selections" (object field selected bare) and "selections can't be made on
+# scalars" (scalar over-selected) bugs before they reach a client runner.
+#
+# This is how the 2026-07-03 LocationStructure `updatedAt` prod failure (and a sibling
+# `createdAt` over-selection in the LocationDraft fragment) were found. Those queries had no
+# spec; this script would have flagged them.
+#
+# It renders each query's block offline (auth is stubbed — no network), assembles its fragments,
+# and validates the full document against a schema introspection JSON.
+#
+# Usage (run under bundler so the graphlient fork's #to_query_string is available):
+#   bundle exec ruby tests/validate_queries.rb [PATH_TO_SCHEMA_INTROSPECTION_JSON]
+#
+# Get a fresh schema JSON via an introspection query against the org's endpoint; the default
+# below points at the last captured dump. Prefer a fresh dump — a stale one yields false
+# "field doesn't exist" noise (harmless: this script only *fails* on the two structural classes).
+
+DEFAULT_SCHEMA = File.expand_path('../.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json', __dir__)
+STRUCTURAL = ['must have selections', "can't be made on scalars"].freeze
+
+schema_path = ARGV[0] || DEFAULT_SCHEMA
+unless File.exist?(schema_path)
+  warn "Schema introspection JSON not found: #{schema_path}"
+  warn 'Pass a path: bundle exec ruby tests/validate_queries.rb <schema.json>'
+  exit 2
+end
+
+# Build a client offline — stub the session token so no network/creds are needed for rendering.
+Ecoportal::API::Common::GraphQL::Client.class_eval do
+  def session_token(*_args, **_kwargs)
+    'dummy'
+  end
+end
+client = Ecoportal::API::Common::GraphQL::Client.new(
+  email: 'validate@local', pass: 'x', org_id: 'validate', host: 'live.ecoportal.com', no_schema: true
+)
+schema = GraphQL::Schema.from_introspection(JSON.parse(File.read(schema_path)))
+
+# Collect every concrete query class (recursively, incl. nested like LocationStructure::Draft).
+query_classes = []
+collect = lambda do |mod|
+  mod.constants.each do |const|
+    obj = begin
+      mod.const_get(const)
+    rescue StandardError
+      next
+    end
+    next unless obj.is_a?(Module)
+
+    query_classes << obj if obj.is_a?(Class) && obj.private_method_defined?(:basic_block)
+    collect.call(obj)
+  end
+end
+collect.call(Ecoportal::API::GraphQL::Query)
+query_classes.uniq!
+
+structural_bugs = {}
+other_errors    = {}
+render_skips = []
+
+query_classes.sort_by(&:name).each do |klass|
+  inst = klass.new(client)
+  query_str = client.to_query_string(&inst.send(:basic_block))
+  fragments = begin
+    inst.send(:assemble_fragments, query_str)
+  rescue StandardError
+    ''
+  end
+  full = fragments.to_s.empty? ? query_str : "#{query_str}\n\n#{fragments}"
+  messages = schema.validate(full).map(&:message)
+  bugs  = messages.select { |m| STRUCTURAL.any? { |s| m.include?(s) } }
+  other = messages - bugs
+  structural_bugs[klass.name] = bugs  unless bugs.empty?
+  other_errors[klass.name]    = other unless other.empty?
+rescue StandardError => e
+  render_skips << "#{klass.name} — #{e.class}: #{e.message}"
+end
+
+puts "Validated #{query_classes.size} query classes against #{File.basename(schema_path)}\n\n"
+
+puts '## STRUCTURAL BUGS (fail the build — bare object / over-selected scalar):'
+if structural_bugs.empty?
+  puts '  none ✅'
+else
+  structural_bugs.each { |name, msgs| puts "  #{name}\n    - #{msgs.join("\n    - ")}" }
+end
+
+puts "\n## OTHER validation findings (verify — may be schema-dump staleness or union handling):"
+if other_errors.empty?
+  puts '  none'
+else
+  other_errors.each { |name, msgs| puts "  #{name}\n    - #{msgs.first(3).join("\n    - ")}" }
+end
+
+unless render_skips.empty?
+  puts "\n## RENDER-SKIPS (could not auto-render — check manually):"
+  render_skips.each { |s| puts "  #{s}" }
+end
+
+exit(structural_bugs.empty? ? 0 : 1)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-graphql
 version: !ruby/object:Gem::Version
-  version: 1.3.9
+  version: 1.3.10
 platform: ruby
 authors:
 - Oscar Segura
@@ -830,6 +830,7 @@ files:
 - tests/loc_structure_update.rb
 - tests/loc_structures_get.rb
 - tests/local_libs.rb
+- tests/validate_queries.rb
 homepage: https://www.ecoportal.com
 licenses:
 - MIT