ecoportal-api-graphql 1.3.13 → 1.3.15

data/.ai-assistance/skills/refactor/SKILL.md

@@ -1,62 +1,62 @@
-# SKILL: Refactor
-
-**Purpose:** Identify, log, and (with developer confirmation) apply refactoring opportunities. Never apply changes without explicit confirmation.
-
----
-
-## When to Use
-
-- You notice a structural issue while working on something else — log it, don't fix it silently.
-- The developer asks for a refactor audit of an area.
-- A cycle-end review surfaces cleanup opportunities.
-
----
-
-## Criteria for a Refactor Candidate
-
-Flag something when it fails one or more of:
-
-- **Understandability:** Is it clear what this does and why?
-- **Dependency tracking:** Are dependencies implicit or tangled?
-- **Separation of concerns:** Is this class/method doing more than one thing?
-- **Simplicity:** Could this be simpler without losing correctness?
-- **Alignment:** Does this match the conventions of the rest of the codebase?
-
----
-
-## Log Format
-
-Refactoring opportunities are logged in `.ai-assistance/code/refactoring/<area>.md`.
-
-Each entry:
-
-```markdown
-## [SHORT-ID] <Title>
-
-- **File(s):** `lib/ecoportal/...`
-- **Type:** [extract_class | extract_method | rename | simplify | reorganise | other]
-- **Priority:** [high | medium | low]
-- **Status:** [open | confirmed | applied | dismissed]
-- **Identified:** YYYY-MM-DD
-
-**Observation:**
-What the issue is, concisely.
-
-**Proposed change:**
-What you'd do to fix it. High-level — not code unless it's very short.
-
-**Risk:**
-Any backwards-compat or downstream risk if applied.
-```
-
----
-
-## Workflow
-
-1. Identify opportunity → log it in the appropriate refactoring file.
-2. Present a summary to the developer: "I've logged N refactoring opportunities in `.ai-assistance/code/refactoring/`. Want to review them?"
-3. Developer confirms which ones to apply → mark as `confirmed`.
-4. Apply one at a time, update specs if needed, mark as `applied`.
-5. If dismissed by developer → mark as `dismissed` with a brief reason.
-
-**Never apply a refactor without a `confirmed` status.**
+# SKILL: Refactor
+
+**Purpose:** Identify, log, and (with developer confirmation) apply refactoring opportunities. Never apply changes without explicit confirmation.
+
+---
+
+## When to Use
+
+- You notice a structural issue while working on something else — log it, don't fix it silently.
+- The developer asks for a refactor audit of an area.
+- A cycle-end review surfaces cleanup opportunities.
+
+---
+
+## Criteria for a Refactor Candidate
+
+Flag something when it fails one or more of:
+
+- **Understandability:** Is it clear what this does and why?
+- **Dependency tracking:** Are dependencies implicit or tangled?
+- **Separation of concerns:** Is this class/method doing more than one thing?
+- **Simplicity:** Could this be simpler without losing correctness?
+- **Alignment:** Does this match the conventions of the rest of the codebase?
+
+---
+
+## Log Format
+
+Refactoring opportunities are logged in `.ai-assistance/code/refactoring/<area>.md`.
+
+Each entry:
+
+```markdown
+## [SHORT-ID] <Title>
+
+- **File(s):** `lib/ecoportal/...`
+- **Type:** [extract_class | extract_method | rename | simplify | reorganise | other]
+- **Priority:** [high | medium | low]
+- **Status:** [open | confirmed | applied | dismissed]
+- **Identified:** YYYY-MM-DD
+
+**Observation:**
+What the issue is, concisely.
+
+**Proposed change:**
+What you'd do to fix it. High-level — not code unless it's very short.
+
+**Risk:**
+Any backwards-compat or downstream risk if applied.
+```
+
+---
+
+## Workflow
+
+1. Identify opportunity → log it in the appropriate refactoring file.
+2. Present a summary to the developer: "I've logged N refactoring opportunities in `.ai-assistance/code/refactoring/`. Want to review them?"
+3. Developer confirms which ones to apply → mark as `confirmed`.
+4. Apply one at a time, update specs if needed, mark as `applied`.
+5. If dismissed by developer → mark as `dismissed` with a brief reason.
+
+**Never apply a refactor without a `confirmed` status.**

data/.ai-assistance/skills/spec-generation/SKILL.md

@@ -1,72 +1,72 @@
-# SKILL: Spec Generation
-
-**Purpose:** Add RSpec specs that guard backwards compatibility and document expected behaviour, placed in the correct spec folder mirroring the lib/ structure.
-
----
-
-## When to Use
-
-- A change could break downstream consumers (primarily `eco-helpers`).
-- A public method or interface is being added, changed, or removed.
-- A bug is fixed — add a regression spec.
-- A new class is added that other code will depend on.
-
----
-
-## Placement Rules
-
-Spec files **mirror `lib/` structure** under `spec/`:
-
-| Code file | Spec file |
-|-----------|----------|
-| `lib/ecoportal/api/graphql/model/action.rb` | `spec/ecoportal/api/graphql/model/action_spec.rb` |
-| `lib/ecoportal/api/graphql/input/location_structure/draft.rb` | `spec/ecoportal/api/graphql/input/location_structure/draft_spec.rb` |
-
-Create the folder path if it doesn't exist.
-
----
-
-## Spec Requirements
-
-Each spec file for a changed area must have:
-
-1. A description of the class/module under test.
-2. At least one spec covering the public interface being changed.
-3. For backwards-compat specs: a comment `# backwards-compat` so they're easily searched.
-
-**Minimum spec template:**
-
-```ruby
-# frozen_string_literal: true
-
-RSpec.describe Ecoportal::API::Graphql::<ClassName> do
-  # backwards-compat
-  describe '#<method>' do
-    subject { described_class.new(<args>) }
-
-    it '<expected behaviour>' do
-      expect(subject.<method>).to <matcher>
-    end
-  end
-end
-```
-
----
-
-## Linked to Code Specs for AI
-
-Whenever a spec file is created or updated for an area, check the corresponding `.ai-assistance/code/<area>.md` doc:
-- Does it mention this class/method?
-- Does it reflect the current expected behaviour?
-
-If not — update it. This redundancy is intentional: it saves AI agents from having to parse spec files to understand expected behaviour.
-
----
-
-## Gemini Assist Integration
-
-When generating specs for a large area, you may use `gemini-assist` to:
-- Get a first-pass draft of spec cases given the source file.
-- Check for edge cases you may have missed.
-
-Always verify the generated specs run and match actual behaviour before committing.
+# SKILL: Spec Generation
+
+**Purpose:** Add RSpec specs that guard backwards compatibility and document expected behaviour, placed in the correct spec folder mirroring the lib/ structure.
+
+---
+
+## When to Use
+
+- A change could break downstream consumers (primarily `eco-helpers`).
+- A public method or interface is being added, changed, or removed.
+- A bug is fixed — add a regression spec.
+- A new class is added that other code will depend on.
+
+---
+
+## Placement Rules
+
+Spec files **mirror `lib/` structure** under `spec/`:
+
+| Code file | Spec file |
+|-----------|----------|
+| `lib/ecoportal/api/graphql/model/action.rb` | `spec/ecoportal/api/graphql/model/action_spec.rb` |
+| `lib/ecoportal/api/graphql/input/location_structure/draft.rb` | `spec/ecoportal/api/graphql/input/location_structure/draft_spec.rb` |
+
+Create the folder path if it doesn't exist.
+
+---
+
+## Spec Requirements
+
+Each spec file for a changed area must have:
+
+1. A description of the class/module under test.
+2. At least one spec covering the public interface being changed.
+3. For backwards-compat specs: a comment `# backwards-compat` so they're easily searched.
+
+**Minimum spec template:**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe Ecoportal::API::Graphql::<ClassName> do
+  # backwards-compat
+  describe '#<method>' do
+    subject { described_class.new(<args>) }
+
+    it '<expected behaviour>' do
+      expect(subject.<method>).to <matcher>
+    end
+  end
+end
+```
+
+---
+
+## Linked to Code Specs for AI
+
+Whenever a spec file is created or updated for an area, check the corresponding `.ai-assistance/code/<area>.md` doc:
+- Does it mention this class/method?
+- Does it reflect the current expected behaviour?
+
+If not — update it. This redundancy is intentional: it saves AI agents from having to parse spec files to understand expected behaviour.
+
+---
+
+## Gemini Assist Integration
+
+When generating specs for a large area, you may use `gemini-assist` to:
+- Get a first-pass draft of spec cases given the source file.
+- Check for edge cases you may have missed.
+
+Always verify the generated specs run and match actual behaviour before committing.

data/.gitignore

@@ -1,37 +1,37 @@
-# it's a gem, ignore the lockfile
-Gemfile.lock
-
-.env
-.ai-assistance/local_paths.md
-# build artifacts
-*.gem
-/.bundle/
-/vendor/bundle
-/spec/reports/
-/tmp/
-/pkg/
-
-# docs
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-
-# rspec failure tracking
-.rspec_status
-scratch.rb
-tests/.byebug_history
-
-.solargraph.yml
-
-# AI assistance — local-only files
-.ai-assistance/code/dep-graph.json
-.ai-assistance/tmp/
-.ai-assistance/local/
-.ai-assistance/bridge/inbox/*.draft.md
-.ai-assistance/bridge/inbox/*.local.md
-.ai-assistance/bridge/LOCK
-.ai-assistance/bridge/STATUS
-.ai-assistance/capabilities/.env
-.ai-assistance/scripts/*.env
-.ai-assistance/scripts/node_modules/
+# it's a gem, ignore the lockfile
+Gemfile.lock
+
+.env
+.ai-assistance/local_paths.md
+# build artifacts
+*.gem
+/.bundle/
+/vendor/bundle
+/spec/reports/
+/tmp/
+/pkg/
+
+# docs
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+
+# rspec failure tracking
+.rspec_status
+scratch.rb
+tests/.byebug_history
+
+.solargraph.yml
+
+# AI assistance — local-only files
+.ai-assistance/code/dep-graph.json
+.ai-assistance/tmp/
+.ai-assistance/local/
+.ai-assistance/bridge/inbox/*.draft.md
+.ai-assistance/bridge/inbox/*.local.md
+.ai-assistance/bridge/LOCK
+.ai-assistance/bridge/STATUS
+.ai-assistance/capabilities/.env
+.ai-assistance/scripts/*.env
+.ai-assistance/scripts/node_modules/

data/.gitlab-ci.yml

@@ -1,18 +1,24 @@
 # CI pipeline for ecoportal-api-graphql
 #
-# First automated check on merge requests. Runs the RSpec suite NON-BLOCKING
-# (allow_failure: true) — it reports pass/fail status without gating merges.
-# Rationale (2026-07-10): add visibility now; tighten to a blocking gate later
-# once the suite is reliably green on a clean runner.
+# Two jobs, deliberately different in strictness:
 #
-# Live/AI specs (tagged :live) are excluded: they need ANTHROPIC_API_KEY + network.
-# They already self-skip when the key is absent, but ~live keeps the runner off
-# that path entirely.
+#   rspec            — NON-BLOCKING (allow_failure: true): reports pass/fail without gating merges.
+#                      Rationale (2026-07-10): visibility now; tighten to a gate later once the
+#                      suite is reliably green on a clean runner.
+#   validate-queries — BLOCKING: renders EVERY query + mutation in the gem against a FRESHLY
+#                      introspected schema and fails only on deterministic, non-negotiable
+#                      breakage (see below). This is the gate the 2026-07-03 v1.3.10 prod hotfix
+#                      (LocationStructure `updatedAt`) called for — those queries had no spec and
+#                      first broke in a client runner.
+#
+# Live/AI specs (tagged :live) are excluded from rspec: they need ANTHROPIC_API_KEY + network.
+# They already self-skip when the key is absent, but ~live keeps the runner off that path entirely.
 #
 # NOTE: graphlient resolves from a git fork (see Gemfile); ecoportal-api / -v2 come
 # from rubygems. If a required floor (e.g. ecoportal-api-v2 >= 3.3.3) is not yet
-# published, `bundle install` may fail on the runner — because this job is
-# allow_failure, that surfaces as a warning rather than blocking the MR.
+# published, `bundle install` may fail on the runner. For `rspec` that surfaces as a
+# warning; for `validate-queries` it fails the pipeline — the fix is to publish the
+# floor gem, not to relax the gate.
 
 workflow:
   rules:
@@ -27,10 +33,8 @@ workflow:
 stages:
   - test
 
-rspec:
-  stage: test
+.ruby:
   image: ruby:3.2.2
-  allow_failure: true          # non-blocking: surface failures, do not gate merges
   variables:
     BUNDLE_PATH: vendor/bundle  # cache installed gems between pipelines
   cache:
@@ -41,5 +45,53 @@ rspec:
     - ruby -v
     - gem install bundler
     - bundle install --jobs "$(nproc)" --retry 3
+
+rspec:
+  extends: .ruby
+  stage: test
+  allow_failure: true          # non-blocking: surface failures, do not gate merges
   script:
     - bundle exec rspec --tag ~live --format progress
+
+# Offline validation of every gem query + mutation against the LIVE schema.
+#
+# Fails the pipeline on exactly two deterministic classes (see tests/validate_queries.rb):
+#   1. FRAGMENT / RENDER FAILURES — the operation cannot even be rendered (dead fragment
+#      reference / unresolved constant). This is what broke the live LocationDraft, Action and
+#      ContractorEntity paths.
+#   2. STRUCTURAL BUGS — "field must have selections" (object field selected bare) and
+#      "selections can't be made on scalars" (scalar over-selected).
+# Everything else (unknown fields etc.) is reported but does NOT fail: it is usually schema
+# staleness or union handling, and needs a human read.
+#
+# The schema is introspected AT PIPELINE TIME on purpose — a committed 6.3MB dump goes stale,
+# and a stale schema both invents noise and hides real findings.
+#
+# Required CI/CD variables (Settings → CI/CD → Variables; mask the password):
+#   EP_CI_SERVER      host of a NON-PRODUCTION environment (e.g. an internal/UAT host)
+#   EP_CI_ORG_ID      organisation id on that host
+#   EP_CI_USER_EMAIL  service account with READ access only — introspection needs no write scope
+#   EP_CI_USER_PASS   its password (masked)
+# Until all four are set the job does not run, so the gate is inert rather than red. Use a
+# service account on a non-production org: the job only ever issues an introspection query,
+# never touches records.
+validate-queries:
+  extends: .ruby
+  stage: test
+  rules:
+    - if: '$EP_CI_SERVER && $EP_CI_ORG_ID && $EP_CI_USER_EMAIL && $EP_CI_USER_PASS'
+  variables:
+    BUNDLE_PATH: vendor/bundle
+    # The gem reads its connection from these names (Common::GraphQL::AuthService).
+    SERVER: $EP_CI_SERVER
+    ORGANIZATION_ID: $EP_CI_ORG_ID
+    USER_EMAIL: $EP_CI_USER_EMAIL
+    USER_PASS: $EP_CI_USER_PASS
+  script:
+    - bundle exec ruby tests/dump_schema.rb ci_schema.json
+    - bundle exec ruby tests/validate_queries.rb ci_schema.json
+  artifacts:
+    when: on_failure           # keep the exact schema the failure was diagnosed against
+    expire_in: 1 week
+    paths:
+      - ci_schema.json

data/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.15] - 2026-07-30
+
+**Backwards-compatible.** Every change here fixes a query or mutation document that the live
+schema rejected — i.e. code paths that could not run at all — plus the CI gate that found them.
+Cherry-picked onto the 1.3.x line from `main`, where they landed alongside **breaking** changes
+that are deliberately NOT in this release (see "Deferred to 1.4.0" below).
+
+### Fixed
+
+- **`FileUpload::Client` authenticated the v2 REST endpoints wrongly.** The ported S3
+  register/poll steps sent `Authorization: Bearer <oauth_token>`; those endpoints authenticate via
+  `X-ECOPORTAL-API-KEY`, so step 3 404'd and `#upload` never completed. `Ecoportal::API::GraphQL.new`
+  accepts an additive `api_key:` (independent of the GraphQL endpoint's own email/pass OAuth),
+  `HttpClient#api_key` is public, and the client raises a clear error when it is missing.
+  ⚠ **Not yet live-verified** — verify against a sandbox org before relying on it.
+- **Three invalid union selections.** `Query::RegisterPresetViews` (`fieldConfigurations`),
+  `Query::PageWithForces` (`forces`) and `Query::PagesWorkflowCommands` (`workflow`) selected
+  fields directly on a union, which is invalid GraphQL ("Selections can't be made directly on
+  unions") — all three queries failed outright. They now select through the members' shared
+  interface (`FieldConfigurationInterface` / `BasePageInterface`). Response shapes are unchanged.
+- **`fragment ForceFields` asked for a non-existent `id` on bindings.** `Force.bindings` is
+  `[BindingInterface]`, whose only fields are `name` / `referenceId` (+ per-member `reference`),
+  so every query spreading the fragment was invalid. Now selects on the interface directly.
+  NOTE the read/write asymmetry this exposes: `WorkflowEditBindingInput` / `removeBinding` require
+  a binding `id` that no read exposes, so `BindingCollection#delete!(binding)` has no source for it.
+- **7 invalid `PageFields` spreads.** The four review-task mutations return `item: TaskInterface`
+  (not a page — the page is reachable via `subject`), `Template::{Create,Destroy}RelatedPage`
+  return `RelatedPages`, and `Template::UpdateInformation` returns the narrow `Template` type. New
+  `:PageTaskFields` / `:TemplateRelatedPages` / `:TemplateInformation` fragments and read-only
+  `Base/Model::Page::Task` + `Base/Model::Template::{RelatedPages,Information}` models; the payload
+  `item_class`es pointed at `Model::PageUnion`, which never matched the schema. The template
+  mutations that genuinely return a page (`Create`/`Publish`/`Unpublish`/`Update`) are unchanged.
+- **6 payloads selected an `item` their type does not have.** `Page::CreateDraft` → `{ id }`,
+  `Page::{DeleteDraft,PublishDraft}` → `{ ok }`, `Page::BatchUpdateReviewTask` → `{ count }` (and
+  its own `Payload::Page::ReviewTaskBatch`), `Register::Destroy` → `{ ok }`, `PresetView::Destroy`
+  → `{ clientMutationId errors }`. `Payload::Page::Draft` gained `id`/`ok`, `Payload::Register`
+  gained `ok`.
+- **`executeWorkflowCommands` was rendered with arguments it never accepted** — the schema takes a
+  single `input: ExecuteWorkflowCommandsInput!`, so the **page-level command bus could not run**.
+  Both classes' `#query` already built the right `input` hash; only the documents were wrong.
+- **`Payload::OkPayload` now models `errors`** — it selected them but computed `success?` purely
+  from `ok`, silently ignoring a populated errors object.
+
+### Added (tooling — no runtime effect)
+
+- **`validate-queries` CI job** (`.gitlab-ci.yml`): renders every query + mutation against a
+  freshly introspected schema and fails on render failures plus the always-invalid selection
+  classes ("must have selections", "can't be made on scalars", "can't be made directly on unions",
+  "can't be spread inside"). This gate is what found everything above.
+- **`tests/dump_schema.rb`**: fresh introspection through the gem's own `HttpClient`. Requires
+  `SERVER` explicitly (the gem's default host is production). Schema dumps are never committed.
+
+### Deferred to 1.4.0 (breaking — intentionally absent here)
+
+- The AI-summary rewire (`generateAiSummary` → `generatePageSummary`,
+  `submitAiSummaryFeedback` → `submitPageAiSummaryFeedback`, changed `#query` keywords,
+  `Base::AiSummaryVersion` field removals) and the removal of the `SmartFill` mutations
+  (`smartFillGenerate` / `smartFillSubmitFeedback` do not exist in the schema).
+- The 2026-07-13 `WorkflowCommandInput` schema sync and the polymorphic read-model layer.
+
+## [1.3.14] - 2026-07-16
+
+Re-issue of the **1.3.13 HttpClient resilience fix** under a fresh version. The `1.3.13`
+artifact published to the gem server (2026-07-11) could not be relied upon to contain the
+fix below — RubyGems versions are immutable and cannot be re-pushed, so the fix ships here
+as `1.3.14`. Functionally identical to the *intended* `1.3.13` (this is `1.3.12` + the
+resilience fix, nothing else). **Backwards-compatible.**
+
+Consumers that need the 429/1015 resilience (e.g. bulk `cans-upsert` live runs) must floor
+`ecoportal-api-graphql >= 1.3.14` — a `>= 1.3.13` floor is not sufficient.
+
+### Fixed
+
+- Same fix as documented under `[1.3.13]` below: `Common::GraphQL::HttpClient#execute` routes
+  through the inherited `instrument → with_retry { rate_throttling }` pipeline, so a single
+  HTTP 429 (Cloudflare edge rate-limit `1015`) no longer aborts the run.
+
 ## [1.3.13] - 2026-07-12
 
 Reliability: the GraphQL `HttpClient` now inherits the **same request-resilience

data/changelog.d/fixed-mr51-payload-item-mismatches.md

@@ -0,0 +1,17 @@
+- **Six mutations selected an `item` their payload type does not have** — invalid documents, so
+  none could run. Found by the first live run of the `validate-queries` CI gate (2026-07-30);
+  every replacement selection below is the schema's own shape, verified against a fresh prod
+  introspection:
+  - `Page::CreateDraft` → `CreatePageDraftPayload { id }` (the new draft's page id)
+  - `Page::DeleteDraft` / `Page::PublishDraft` → `{ ok }`
+  - `Page::BatchUpdateReviewTask` → `{ count }` (tasks updated). It also shared
+    `Payload::Page::ReviewTask`, whose type has an `item`; it now has its own
+    `Payload::Page::ReviewTaskBatch`.
+  - `Register::Destroy` → `DestroyRegisterPayload { ok }`
+  - `PresetView::Destroy` → `DestroyPresetViewPayload { clientMutationId errors }` — no payload
+    data at all, not even `ok`.
+  `Payload::Page::Draft` gained `id`/`ok` and `Payload::Register` gained `ok`; the create/update
+  variants of Register/PresetView still return `item` and are untouched. ★ Note `Logic::Payload`'s
+  inherited `embeds_one :item` materialises a HOLLOW item (all fields nil, and it writes
+  `'item' => {}` into the doc) when the response has no `item` — it does not return nil, so read
+  the scalars. 21 specs.

data/docs/worklog.md

@@ -8,24 +8,6 @@ This file tracks cross-project session state and the overall repo status.
 
 ---
 
-## ▶ SESSION 2026-07-10 — OD-001 decision-support delivered to ep-ai-standards (breadcrumb)
-
-Produced a decision-support doc mapping this repo's REAL GraphQL mutation surface onto
-ep-ai-standards' operation-class ladder for OD-001 (the GraphQL gateway PROD "low-risk"
-auto-approval threshold / provisional Dial A). Evidence-based from live introspection
-(`.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json` -- 190 mutations)
-+ code-specs + `lib/ecoportal/api/graphql/mutation/**`. Key findings: register-type axis is
-real + in-schema (`Register.registerStatus: TESTING|LIVE`, `base/register.rb:7`); org-type
-(sandpit/uat/demo/PROD) is NOT a schema field (infra/credential-level, `base/organization.rb`
-exposes only id/name/companyName/logoUrl); several mutations do not map cleanly (payload-hidden
-deletions in `updatePage`, bulk/cascade, cross-env UAT->PROD deploy, egress/email/credential
-mints). Delivered to ep-ai-standards' bridge inbox as
-`ecoportal-api-graphql-od001-mutation-mapping.md` (STATUS: PENDING) -- a PROPOSAL for the graphql
-team + Oscar to validate via an ep-ai-standards MR. NO code changed in this repo. Does not change
-OD-001's ruling. (OD-007 breadcrumb convention.)
-
----
-
 ## ▶ SESSION 2026-07-05 — 3 live act-gov crashes = ONE root cause (stale released gems); fixed-stack floors
 
 Three live crashes on act-gov (`-toocs-coding` + org-structure sync), all the **same class**: the

data/lib/ecoportal/api/common/graphql/client.rb

@@ -29,8 +29,6 @@ module Ecoportal
 
             puts "Configuring GraphQL Client onto '#{url}'"
 
-            pp email
-
             super(
               url,
               headers:      {

data/lib/ecoportal/api/common/graphql/http_client.rb

@@ -21,6 +21,12 @@ module Ecoportal
 
           attr_reader :host, :version
 
+          # Publicly exposes the configured api_key (inherited as `private` from
+          # `Common::Client`) — `FileUpload::Client` needs it directly to authenticate
+          # against the v2 REST endpoints, independent of this client's own `@version`
+          # (which stays `'graphql'` and therefore always builds a Bearer `key_token`).
+          public :api_key
+
           include Ecoportal::API::Common::GraphQL::AuthService
 
           def initialize(

data/lib/ecoportal/api/graphql/base/ai_summary_version.rb

@@ -1,17 +1,17 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        # Represents one generation version of an AiSummary field.
-        # Returned by generateAiSummary — tracks the prompt, output, token usage, and status.
-        class AiSummaryVersion < Logic::BaseModel
-          passkey :id
-          passthrough :aiSummary, :status, :prompt
-          passthrough :inputTokens, :outputTokens, :totalTokens
-          passthrough :resourceType # "field" | "stage" | "page"
-          passarray :ratings        # [[user_id, score], ...]
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # Represents one generation version of an AiSummary field.
+        # Returned by generateAiSummary — tracks the prompt, output, token usage, and status.
+        class AiSummaryVersion < Logic::BaseModel
+          passkey :id
+          passthrough :aiSummary, :status, :prompt
+          passthrough :inputTokens, :outputTokens, :totalTokens
+          passthrough :resourceType # "field" | "stage" | "page"
+          passarray :ratings        # [[user_id, score], ...]
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/location_classification_type.rb

@@ -1,15 +1,15 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        class LocationClassificationType < Logic::BaseModel
-          root!
-
-          passkey :id
-          passthrough :name
-          passboolean :active
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class LocationClassificationType < Logic::BaseModel
+          root!
+
+          passkey :id
+          passthrough :name
+          passboolean :active
+        end
+      end
+    end
+  end
+end