ecoportal-api-graphql 1.3.5 → 1.3.16

data/CHANGELOG.md

@@ -1,477 +1,934 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-
-## [1.3.6] - 2026-05-26
-
-### Added
-
-### Changed
-
-### Fixed
-
-## [1.3.5] - 2026-05-26
-
-### Changed
-
-- Moved `graphql` endpoint to `external/graphql`
-- Missing env var (i.e. `ORG_ID`) will **raise** now an error (instead of just a print)
-
-## [1.3.4] - 2025-09-04
-
-### Added
-
-- Command execution result: **added** command doc when there's a `results` error.
-- Payload improvements:
-  - On `LocationsError.validationErrors`: fetch `property` property.
-  - On **results**, `Command` always fetch `__typename` and the other properties.
-
-### Changed
-
-- Changed base `error_doc`: **consistent property name**
-
-### Fixed
-
-- Correct fetch on `ok` (sometimes it is `null`: that doesn't mean failed).
-- **Consistent order** on `error?` and `error_doc`.
-- `Draft`
-  - **Overlapping** name `ConflictingIds` (vs `LocationsError.conflictingIds`)
-  - **Wrong** include on `FetchNested`
-
-## [1.3.3] - 2025-08-29
-
-### Added
-
-- Better error handling
-
-### Fixed
-
-- Unused parameter/variable `$includeArchivedNodes`
-
-## [1.3.2] - 2025-08-19
-
-### Added
-
-- `Mutation`: allow parameters other than **input**.
-- Location Structure `Draft` models
-- `Interface::LocationStructure::Nodes` for `LocationStructure` and `Draft::Structure`
-- `raw_response` as optional query parameter (for debugging)
-- `Logic::Input` (out of consistency)
-- Fragments:
-  - `LocationDraft`
-  - `LocationsError`
-- Query to include `draft` list when fetching an **RS**.
-- Location `Draft` queries:
-  - `Draft#byId`
-  - `Draft#create`
-  - `Draft#delete`
-  - `Draft#addCommands`
-  - `Draft#publish`
-  - `Draft#dropBadCommands`
-- Error tracking througout the payload models of location mutations
-
-### Changed
-
-- Upgrade dependency (`ecoportal-api` **gem**).
-- Moved rescue on fragment definition to `#define` itself.
-- `NodeInterface` moved to `Interface::LocationStructure::Node`
-- Code: Shorten namespace referral.
-- Swap to `Logic::BaseModel`
-- `Mutation` to introduce `:input` required parameter by using parent class.
-
-### Fixed
-
-- `QueryConnection`: bad code.
-- `conflictingIds` should be array.
-
-## [1.3.1] - 2025-06-11
-
-### Changed
-
-- upgraded gem dependencies
-- **Moded** `Ecoportal::API::GraphQL::Base::Model` to
-  - > `Ecoportal::API::GraphQL::BaseModel`
-- **Added** `Interface::LocationNode`
-- **Added** `Interface::BasePage`
-
-### Fixed
-
-- **Fragments**
-  - `Action` fragment to use `PageUnion` (**upgrade**)
-  - **Memoize** fragments.
-  - Add what fragment failed in the **error**.
-
-## [1.2.1] - 2025-05-16
-
-### Changed
-
-- upgrade `ecoportal-api` gem
-- upgrade `ecoportal-api-v2` gem
-
-## [1.1.1] - 2025-05-14
-
-### Added
-
-- `MemberChanges` helpers for `Base::ContractorEntity`
-- Custom **Diff** logic that can be used in GraphQL content:
-  - `Common::GraphQL::Model::Diffable::HashDiffNesting`
-    - Reused from `HashDiffPatch` (`ecoportal-api-v2`):
-      1. It does not use `patch_ver`, but rather just `id` property alone.
-      2. The _operation_ property has been renamed to `api_operation` (to ensure no collisions). And the operation types are symbols, and renamed to: `:delete`, `:update` and `:create`. This can show up to be useful when, for instance, reusing the output of `#as_update` to generate actual input objects (i.e. `#as_input`) that feed some GraphQL query.
-      3. The _data_ property has been renamed to `change_data`.
-      4. `Hash` **keys** are of type `Symbol`.
-  - `Common::GraphQL::Model::Diffable::DiffService`. In a GraphQL context, this aims to be able to implement a function called `#as_input` (equivalent to `#as_update`):
-      1. It uses the `HashDiffNesting` helpers.
-      2. It has capability to `ignore` certain keys.
-      3. It can calculate **diff** excluding nested models (i.e. those that are `root?` and, therefore, not part of the changed target model). This functionality is an optimization to `cascaded_callbacks` throughout the nested models.
-
-### Changed
-
-- `Common::GraphQL::Model::Diffable` by using `Diffable::DiffService` (with `cascaded_callbacks` implementation).
-  - `#as_update`
-  - `#dirty?`
-- upgraded `ecoportal-api` gem
-- updraded `ecoportal-api-v2` gem
-
-## [0.4.7] - 2025-04-02
-
-### Added
-
-- `page.id` to Action linked resources.
-
-## [0.4.6] - 2025-04-02
-
-### Added
-
-- `Ecoportal::API::GraphQL::Logic::QueryConnection`
-  - **Require** `default_connection_block` to child classes
-  - This aims to **not** having have client code having to define the block for `#each`
-
-### Changed
-
-- upgraded `ecoportal-api` gem
-- upgraded `ecoportal-api-v2` gem
-
-## [0.4.5] - 2025-03-14
-
-### Added
-
-- Query `actionCategories`
-- Mutation **create** `Action`
-
-### Changed
-
-- `Action` model to have `locations` (**RS** upgrade)
-
-## [0.4.4] - 2025-02-23
-
-### Changed
-
-- Upgraded `ecoportal-api` gem (maintanance)
-- Upgraded `ecoportal-api-v2` gem (to provision `root!` class method)
-- Defined some models that hand on their own as `root!`
-- Refactored `Base::Model` by moving its loggic to `Common::GraphQL`
-
-### Fixed
-
-- `Ecoportal::API::Common::GraphQL::HashHelpers`
-  - Truly make the iterator generic
-
-## [0.4.3] - 2024-11-21
-
-### Changed
-
-- upgrade gems
-  - `ecoportal-api`
-  - `ecoportal-api-v2`
-- `Ecoportal::API::Common::GraphQL::HttpClient.new` ceased to default `version` to `v1` (now it defaults to `nil`)
-
-## [0.4.2] - 2024-10-01
-
-### Changed
-
-- upgrade gems
-  - `ecoportal-api-v2`
-- add explicit dependency onto `ecoportal-api` gem (client)
-
-## [0.4.1] - 2024-08-09
-
-### Added
-
-- `ContractorEntity` added field `externalId`
-
-### Changed
-
-- gem upgrade `ecoportal-api-v2`
-
-## [0.4.0] - 2024-08-01
-
-### Changed
-
-- require `ruby 3`
-
-## [0.3.18] - 2024-05-16
-
-### Fixed
-
-- `Ecoportal::API::GraphQL::Payload::LocationStructure::CommandExecutionResult`
-  - Error is nullable
-
-## [0.3.17] - 2024-05-14
-
-### Fixed
-
-- `field_name` should add up to the path
-
-## [0.3.16] - 2024-04-29
-
-### Added
-
-- Exposed `graphql` `ContractorEntity` `destroy`
-
-### Fixed
-
-- incorrect loading
-
-### Changed
-
-- Input for ContractorEntity create moved as `update` (as it wasn't correct)
-
-## [0.3.15] - 2024-04-13
-
-### Added
-
-- `Ecoportal::API::GraphQL::Logic::BaseQuery`
-  - `::base_path` class instance var.
-- query to retrieve `currentOrganization.classifications`
-
-### Fixed
-
-- upgraded `ecoportal-api-v2` gem
-
-## [0.3.14] - 2024-03-13
-
-### Added
-
-- some benchmarking on
-  1. core graphql base `query`
-- `#parent_id` to location node model
-
-### Changed
-
-- upgraded `ecoportal-v2-api` gem
-
-### Fixed
-
-- Optimized `treeify` and locations structure class
-
-## [0.3.13] - 2024-02-03
-
-### Changed
-
-- upgrade `ecoportal-api-v2`
-
-## [0.3.12] - 2024-01-27
-
-### Added
-
-- Exposed `graphql` `Action` `update` and get a single `action`
-
-## [0.3.11] - 2023-09-19
-
-### Added
-
-- Exposed `graphql` `ContractorEntity` `create` and `update`
-
-## [0.3.10] - 2023-08-12
-
-### Fixed
-
-- `Ecopotal::API::GraphQL::Query::LocationStructure`
-  - `query` in basic_block missed an explicitly declared parameter.
-
-## [0.3.9] - 2023-08-03
-
-### Added
-
-- `Ecoportal::API::GraphQL::Logic::BaseQuery`
-  - Added support for **default** values.
-
-## [0.3.8] - 2023-07-18
-
-### Added
-
-- Integration for archiving actions.
-- `LocationNodeInterface` -> support for `classifications`
-- `Treeify` to dump more data per node (classifications)
-
-### Fixed
-
-- Silenced waning messages when redefining `Fragment`s
-
-## [0.3.7] - 2023-05-23
-
-### Fixed
-
-- `Ecoportal::API::Common::GraphQL::Client` adjusted `read_timeout` and `write_timeout` to `90` seconds.
-
-## [0.3.6] - 2023-04-17
-
-### Changed
-
-- Softened max version of **gem** dependencies
-
-### Fixed
-
-- `Ecoportal::API::GraphQL::Fragment#define` was not removing previous constants
-  - Changed check method to be `::const_defined?`
-
-## [0.3.5] - 2023-04-03
-
-### Fixed
-
-- `Ecoportal::API::GraphQL::Helpers::LocationsTree#treeify`
-  - Make it real id-case-insensitive (parents in lower case were being missed due to this)
-
-## [0.3.4] - 2023-04-03
-
-### Added
-
-- `Ecoportal::API::Common::GraphQL::AuthService`
-  - `#session_token` added **token auto-renew** functionality (when token expires in less than 90 minutes)
-  - `#session_token_renewed`
-
-### Fixed
-
-- Enabled to specify `host` (other than `live.ecoportal.com`) by the user
-
-## [0.3.3] - 2023-04-02
-
-### Fixed
-
-- `Ecoportal::API::GraphQL::Base::LocationNode` **added** attribute `archivedToken`
-
-## [0.3.2] - 2023-04-02
-
-### Changed
-
-- `Ecoportal::API::GraphQL::Helpers::LocationsTree#treeify` added support for `archived_token`
-
-## [0.3.1] - 2023-03-09
-
-### Changed
-
-- Upgraded core gem dependency `ecoportal-api-v2`
-
-## [0.2.3] - 2023-02-27
-
-### Fixed
-
-- Typo in tests LocationsStructures... should read `locationStructures`
-
-## [0.2.2] - 2023-02-24
-
-### Fixed
-
-- Build gem correctly
-
-## [0.2.1] - 2023-02-24
-
-### Changed
-
-- Migrate from TagTrees to **reporting structures** (breaking change)
-
-### Added
-
-- Basics for reporting structure mutations
-
-## [0.1.11] - 2022-11-29
-
-### Added
-
-- `Ecoportal::API::GraphQL::Base::Mutation`
-- Added `createContractorEntity`
-
-### Changed
-
-- **upgraded** `graphlient` gem dependency (support for framents)
-  - removed patch in this gem
-- Slight internal refactor of `Ecoportal::API::GraphQL::Base::Query`
-- Upgraded `ecoportal-api-v2` **gem** dependency
-
-## [0.1.10] - 2022-09-29
-
-### Changed
-
-- **upgraded** `ecoportal-api-v2` gem dependency
-
-### Fixed
-
-- Remove debugging message
-
-## [0.1.9] - 2022-09-26
-
-### Added
-
-- `Ecoportal::API::GraphQL::Query::TagTree`
-
-### Changed
-
-- **upgraded** `ecoportal-api-v2` gem dependency
-- added `Ecoportal::API::Common::GraphQL::QueryIntegration`
-  - restructured `Ecoportal::API::GraphQL::Model::Organization` class
-- **Patch** on `Graphlient::Query` for fragments support (**pull request**: <https://github.com/ashkan18/graphlient/pull/94>)
-
-## [0.1.8] - 2022-09-23
-
-### Added
-
-- `currentOrganization.tagTrees` query
-
-### Changed
-
-- **upgraded** `ecoportal-api-v2` gem dependency
-- Restructured the `Query` inheritance chain to make things simpler
-
-## [0.1.6] - 2022-09-19
-
-### Fixed
-
-- Call to **private** method `remove_const` in `Ecoportal::API::GraphQL::Fragment#define`
-
-## [0.1.5] - 2022-09-19
-
-### Added
-
-- Patch `GraphQL::Query#append_node` so we can use Fragments in blocks using `___` as start of the constant, and `__` for namespace separator
-  - Issue/feature request: <https://github.com/ashkan18/graphlient/issues/93>
-- `Ecoportal::API::GraphQL::Fragment#define` provided that client scripts can create their own fragments in their own namespace
-  - Exposed `Ecoportal::API::GraphQL#fragments`
-  - It will always (re)define in the `Fragment` root namespace
-
-## [0.1.4] - 2022-09-16
-
-### Fixed
-
-- Able to inject connection block to `each`
-- Error handling delegated to parent class (`QueryConnection`)
-- Retrieve `id` on elements of `Array`
-
-## [0.1.3] - 2022-09-15
-
-### Fixed
-
-- Fixed circular reference to `org_id` in `Ecoportal::API::Common::GraphQL::Client`
-
-## [0.1.2] - 2022-09-15
-
-### Changed
-
-- `Ecoportal::API::GraphQL` addded `email` and `pass` parameters on initialization
-  - This allows for integration in some client lib
-
-## [0.1.0] - 2022-09-15
-
-### Added
-
-- First commit with some basic structure
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+## [1.3.16] - 2026-08-13
+
+### Fixed
+
+- Packaging-only republish of `1.3.15` with an allowlisted gemspec (backported from `2.0.0`).
+  Versions `1.3.9`-`1.3.15` shipped internal repository content (`.ai-assistance/` project notes,
+  `docs/worklog.md`, architecture docs) to rubygems.org via the old denylist `spec.files`; they
+  will be yanked. `1.3.16` is the identical `lib/` code (including the `1.3.15` OozeRedirect
+  `executeWorkflowCommands` fix) packaged clean, so the `1.x` line keeps a clean latest release.
+
+## [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
+contingencies as the REST clients** instead of a bespoke, divergent request path.
+**Backwards-compatible** — `execute` returns the same parsed body and raises the same
+error classes; only the transport path changed.
+
+### Fixed
+
+- **`Common::GraphQL::HttpClient#execute` no longer bypasses the inherited
+  `Common::Client` pipeline.** It previously issued the POST raw
+  (`base_request.post`) and handled the response itself, so GraphQL requests got
+  **none** of the resilience baked into `ecoportal-api`'s client over the years —
+  a single **HTTP 429** (Cloudflare edge rate-limit, error `1015`) aborted the whole
+  run. `execute` now routes through `instrument` → `with_retry { rate_throttling }`,
+  gaining for free:
+  - **rate-limit backoff** via `rate_throttle_client` (default
+    `ExponentialIncreaseProportionalDecrease`) — 429s are throttled + retried, not fatal.
+  - **retry on 5xx / connection errors** (`WithRetry`, 5 attempts) + empty-body guard.
+  - timeouts, and (deep-)logging / APM instrumentation.
+  - `handle_http_response` now consumes the wrapped `Common::Response` (single body
+    read — also removes a latent double-read hazard). The GraphQL-errors-in-a-200-body
+    path (`ResponseError`) is unchanged.
+  This is convergence on the shared base, so any future contingency added to
+  `Common::Client` now applies to GraphQL automatically.
+
+## [1.3.12] - 2026-07-09
+
+Compat-layer correctness for register **field filters** + the native `SearchConf` field-filter DSL.
+**Backwards-compatible** — bug fixes (broken field filters returned 0 results) + additive methods;
+no public return type changed. (The `get_by_name`→collection contract change is intentionally **not**
+in this release — it is a breaking change parked on `feature/model-input-fixes` for a deliberate,
+signed-off future decision.)
+
+### Fixed
+
+- **`Compat::FilterTranslator`** now routes register **FIELD** filters to the backend-correct ES
+  operation (previously emitted the system-key operation → 0 results):
+  - Date FIELD (key `date.zXXXX`) → `range_date_filter` + `path: membranes.date` (system date keeps
+    `date_filter`).
+  - Select FIELD (key `select_str.zXXXX`) → `has_any_filter` / `doesnt_have_any_filter` +
+    `path: membranes.select_str` + `field_key: 'selected'` (system option key keeps
+    `one_of_filter`/`none_of_filter`).
+  - `exact_filter` no longer derives a `membranes.<type>` path for **system** keys
+    (`external_id`/`id`/`state`) — a spurious path produced term `membranes.external_id.external_id`
+    → 0 results (silent miss → dup-on-upsert). Register FIELD keys still get the nested path.
+  - Verified against the backend filter definitions; catalogued in
+    `.ai-assistance/code/filter_contract_matrix.md`.
+
+### Added
+
+- **`SearchConf` field-filter DSL:** `sc[:'date.zXXXX'].between/since/before` now emits
+  `range_date_filter` + `membranes.date` for register Date FIELDs; new `FieldRef#any_of` / `#none_of`
+  → `has_any_filter` / `doesnt_have_any_filter` (path + `field_key`) for register field value
+  membership (distinct from `one_of`, which ORs `exact_filter` for system keys).
+- **`get_by_id`** on `DataField::Collection` and `SectionCollection` (v2-compat find-by-id) — fixes
+  `NoMethodError` in consumers that resolve a field/section by id.
+
+## [1.3.11] - 2026-07-04
+
+Template automatic **build & maintenance** engine (backwards-compatible — a self-contained new
+`Diff` module + a build emitter; nothing existing changed). Validated **offline** (specs + fixtures +
+shapes checked against the live schema dump); the live UAT→PROD round trip is pending a sandbox org.
+
+### Added
+
+- **`genomeSignature`** fetched on every data-field type (added once to the `dataFieldInterface`
+  fragment, `@skip(if: $only_content)`) + `passthrough :genomeSignature` on `Base::Page::DataField` —
+  a strong-but-fallible field-pairing signal.
+- **`Diff::VersionDiff`** — two same-object (retained-id) template snapshots → an exact structural
+  changelog: added/removed/changed/moved for stages, sections, fields (label/type/section-move),
+  select options (label/weight), **gauge stops** (add/remove/threshold/color, matched by stop id), and
+  typed **`byType` field config** (conservative, only confirmed read↔input-key matches: Gauge `max`;
+  Select `dataType/multiple/flat/other/otherDesc`; Date `showTime/pastOnly/todayButton`).
+- **`Diff::Change`** — command-ready change (`op`/`kind`/`id`/`label`/`path`/`attribute`/`before`/
+  `after`/`parent_id`/`by_type`) with a human `#description`; `#to_h` is the stable interchange shape.
+- **`Diff::CommandSynthesizer`** — a `Change` set → an ordered `WorkflowCommand` batch (the replayable
+  "commit"): moves/renames/config, options, gauge stops, `editFieldConfiguration(byType:)`, with
+  **`placeholderId` threading** so dependent intra-batch creates reference not-yet-created nodes.
+  Genuinely ambiguous cases (field type change, moves without a target id) are left **UNSUPPORTED** —
+  never guessed.
+- **`Diff::Deploy`** — `from_versions(before, after, target_doc:)` / `from_cross_object(...)` produce
+  the ordered batch ready for `executeWorkflowCommands`; `#execute!` refuses to run while the honest
+  `unsupported` list is non-empty unless `allow_partial: true`; inert until an executor is passed.
+- **`Diff::IdResolver`** — indexes a target doc's stage names + section headings → ids for move
+  resolution; duplicate keys resolve to `nil` (never guesses).
+- **`Diff::Pairing::{Engine,Signals,Candidate,Ledger}`** — multi-signal equivalence matching for
+  cross-object templates (genome 0.5 + type 0.2 + label 0.2 + options-by-value 0.1, averaged over
+  applicable signals; greedy 1:1; auto-accept ≥0.85, ambiguous 0.5–0.85, unmatched <0.5; genome
+  mismatch scores 0 but does **not** veto). `Ledger` persists confirmed pairs (consulted first;
+  human corrections supersede).
+- **`Diff::Strategy`** — composable diff modalities: pairing (`:id`/`:genome`/`:type_label`/
+  `:assisted`) × scope (`:structural`/`:config_only`/`:data_migration`) × move-sensitivity × intent
+  (`:changelog`/`:deploy`/`:sync_readiness`). `.default` reproduces exact pre-existing behaviour.
+- **`Diff::CrossObjectDiff`** — diffs two templates with **no shared ids** by building the
+  id-correspondence map via `Pairing::Engine` (+ optional `Ledger`), then emitting the same `Change`
+  output that feeds `CommandSynthesizer`/`Deploy`. Ambiguous/unmatched held in `#unresolved` for a
+  human — never auto-paired.
+- **`Builder::TemplateBuilder`** — a declarative template spec (stages→sections→fields→options→
+  config→gauge-stops) → an ordered `WorkflowCommand` batch for `Builder::Template#create/update`,
+  using the **same `placeholderId` threading** as the diff synthesizer so build-from-scratch and
+  diff-deploy emit through one layer. Emits only verified input `VALID_KEYS`. A field's `description`
+  (e.g. a CSV/hidden-field identity token) is emitted as a follow-up `editFieldConfiguration(
+  dataFieldId:, description:)` — the correct schema seam, since `WorkflowAddFieldInput` has no
+  `description` key.
+- **Stage/section back-refs on added nodes** (`Diff::CommandSynthesizer`) — an added field's `addField`
+  now carries `sectionId` (`Change#parent_id`) + `stageId` (new `Change#owner_id`); an added section
+  emits a follow-up `addStageSection(stageId:, sectionId:)`. All threaded via `ref()` (parent
+  placeholder when created same-batch, else real id; omitted when unknown → historical behaviour
+  unchanged). `VersionDiff` records `parent_id`/`owner_id` on added field/section changes.
+
+### Fixed
+
+- **Fragment references migrated to the `spread :Name` registry convention.** The Action and
+  ContractorEntity **mutations** (`create`/`update`/`destroy`, `create`/`update`/`archive`) still used
+  the dead `___Const__Fragment` convention, which resolves a Ruby constant `Fragment::<Name>` that no
+  longer exists (fragments are a registry now) → `uninitialized constant … Fragment::… (NameError)` at
+  render time. Now `spread :Action` / `spread :ContractorEntity`, matching the already-migrated queries.
+  (The sibling breakage in eco-helpers' location-command optimizations is fixed in eco-helpers 3.2.17;
+  it crashed the live act-gov locations sync.)
+- **Kickstand workflow mutations — bare `DateTime` selection.** `Kickstand::{Start,Stop,Fail}Workflow`
+  selected `startedAt`/`stoppedAt`/`failedAt` bare → "Field must have selections". Now
+  `{ dateTime timeZone }` (same class as the 1.3.10 LocationStructure fix).
+- **`tests/validate_queries.rb` now renders MUTATIONS too** (was queries only) and **hard-fails on a
+  render error** (dead fragment / unresolved constant), not just a soft skip — the offline guard for
+  both classes above. It caught the 3 Kickstand bugs immediately.
+
+### Schema realities (verified against the live introspection dump)
+
+- **`required` cannot be set via the workflow command bus** — there is NO `required` input key anywhere
+  in the schema (not on `WorkflowAddFieldInput`, not on `WorkflowEditFieldConfigurationInput` or any of
+  its 12 byType sub-inputs). Callers must treat field-`required` as **read-only / out-of-band**
+  (ecoportal-qa `:skip`s `required`-readiness by design).
+
+### Dependencies
+
+- **Requires `ecoportal-api-v2 >= 3.3.3`** (was `>= 3.3.2`). 3.3.2 has a Ruby-3.x `TypeError` in the
+  `DoubleModel` cascade (`_cascaded_attributes_trace`) that crashes `as_update`/`DiffService` on any
+  model with nested attributes — fixed in v2 3.3.3. Raising the floor stops the broken v2 from
+  resolving on consumers.
+
+### Known gaps (tracked, not in this release)
+
+- Live characterization (UAT→PROD replay + verify) is pending a sandbox org + credentials.
+
+## [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
+integrations (toocs-coding, cans-upsert).
+
+### Fixed
+
+- **Faithful dry-run body** — `Compat::Pages#get_body` returns the SAME input `#update`/`#create`
+  would send (under the `'page'` key), incl. `dataFields.updates` (invisible to `page.as_update`
+  on phased pages). Create previews render as `CreateFromTemplateInput` (marker-based
+  `#new_draft?`) instead of mislabelling as updates.
+- **Stage submit/sign-off carries `stageId`** — `Input::Page::Update.from_model` raises if a
+  submit/task is requested without a stage; `Compat::StageView` records the viewed stage on the
+  page; `compat_stage_id` resolves pinned → active(stage-view) → current. People-field
+  permissions are stage-scoped, so a submit must name its stage.
+- **`CrossReference#dirty?`** compares the reference-id SET vs `original_doc` — no phantom
+  `referenceIds: []` clears (empty→empty / same→same is not dirty).
+- **`Number`/`Gauge` blank → nil, never `0.0`** — an empty CSV cell no longer coerces to a real
+  zero. Shared `DataField#numeric_or_nil`.
+- **`People` reader** falls back to the `people{id}` nodes when `peopleIds` is blank — an append
+  can't wipe existing people.
+- **`Compat::Pages#create` resolves `templateId` from the get_new marker**
+  (`_compat_source_template_id`), matching the dry-run — fixes a live `templateId: null` failure.
+
+### Added
+
+- **Exact-match register filter** — `Compat::FilterTranslator` maps a v2 `type: 'exact_filter'`
+  (alias `'is_filter'`) → GraphQL `is_filter` (whole-value equality on a field's `.exact` keyword
+  subfield), deriving the `membranes.<type>` path. Fixes exact-id existence checks (partial
+  `match_filter` missed exact SKUs → duplicate pages). Note: case-insensitive, first-64-chars.
+- **`Builder::Page#archive(clear_external_id:)`** — optionally blanks `externalId` (a separate
+  `updatePage`) before archiving, for cleanup of a failed/duplicate creation; default `false`
+  keeps it. externalId is the per-org, per-model integration pairing key.
+
+## [1.3.8] - 2026-06-12
+
+### Added
+
+- **Template mutations** — full lifecycle for creating and updating workflow templates:
+  - `Mutation::Template::{Create,Update}` — `createPageTemplate` / `updatePageTemplate` (both accept `WorkflowCommandInput` command bus)
+  - `Mutation::Template::{Publish,Unpublish}` — `publishTemplate` / `unpublishTemplate`
+  - `Mutation::Template::UpdateInformation` — update template `description`, `aiDescription`, `templateType`
+  - `Mutation::Template::{CreateRelatedPage,DestroyRelatedPage}` — manage template related-pages
+  - `Builder::Template` wired as `api.template`
+- **`updateVariableBindings`** — `Mutation::Page::UpdateVariableBindings` maps named force variable slots to data field IDs on a page; `Input::VariableBinding` value object
+- **Kickstand job mutations** — `Mutation::Kickstand::{StartJob,FailJob,BulkUpdateJobs}`; `Builder::Kickstand` extended with `start_job`, `fail_job`, `bulk_update_jobs`
+
+## [1.3.7] - 2026-06-12
+
+### Added
+
+- **PagesWorkflow space (W1–W5)**
+  - `Base::PagesWorkflow` + sub-model tree (`pages_workflow/`): `RegisterField`, `CallbackType`,
+    `OperationInterface`, `TriggerInterface`, and supporting types — read model for the
+    page-workflow configuration (`autoPageCreationEnabled`, `fields`, `stages`).
+  - `Model::PagesWorkflow` with class resolver.
+  - **Workflow command bus**: `Input::WorkflowCommandInput` covering ~80 command types under
+    `input/workflow_command/`. `Mutation::Page::ExecuteWorkflowCommands` +
+    `Payload::ExecuteWorkflowCommands`.
+  - Workflow fragments registered for assembly.
+  - _Note: the workflow command surface is volatile upstream — designed to absorb change._
+- **Force model / ForceCompat**
+  - `Base::Force` (+ `force/` sub-models), Force fragment.
+  - `Mutation::Page::ExecuteForceCommands`, `Payload::ForceCommands`, `Query::PageWithForces`.
+- **DataField type hierarchy (Phase E)**
+  - Full set of typed `Base::Page::DataField` subclasses: `PlainText`, `RichText`, `DateField`,
+    `Number`, `Gauge`, `People`, `Select`, `Checklist`, `TagField`, `Geo`, `Signature`,
+    `ContractorEntities`, `CrossReference`, `ImageGallery`, `FileField`, `Mailbox`,
+    `ActionsList`, `Law`, `AiSummary`, `Table`, `SmartFill`, dispatched via `TYPE_MAP`/`from_doc`.
+  - `DataField::Collection` — `dirty_inputs`, `dirty_additions`, `dirty_deletions`,
+    `add`, `mark_for_deletion`.
+- **Register builder & models**
+  - `Builder::Register` (+ `register/preset_view`), `Model::Register`,
+    `Mutation::Register` (`create`/`update`/`destroy`), `Input::Register`, `Payload::Register`.
+- **Preset views**
+  - `Model::PresetView`, `Mutation::PresetView` (`create`/`update`/`destroy`/`permission`),
+    `Query::RegisterPresetViews`, `Input::PresetView`, `Payload::PresetView`.
+- **AI mutations**
+  - `Mutation::SmartFill` (`generate`/`submit_feedback`).
+  - `Mutation::AiSummary` (`generate`/`submit_feedback`), `Model::AiSummaryVersion`,
+    `Payload::AiSummaryGenerate`.
+- **Review task & draft lifecycle mutations**
+  - Review tasks: `approve`/`reject`/`restart`/`undo`/`batch_update` (`Mutation::Page::*ReviewTask`),
+    `Payload::Page::ReviewTask`.
+  - Drafts: `Mutation::Page::CreateDraft`/`PublishDraft`/`DeleteDraft`, `Payload::Page::Draft`.
+  - Templates: `Mutation::Page::BuildFromTemplate`/`CreateFromTemplate` + payloads.
+- **Queries**
+  - `Query::PageDelta` (+ `Base::DeltaResult`, `Input::DeltaInput`).
+  - `Query::RegisterPreviewPages` (+ `Base::PreviewPage`).
+  - `Query::FileUploadSignature` + file-upload helper.
+- **`Input::SearchConf`** — fluent/chainable filter DSL and `SearchConf.from_description`
+  (AI-assisted filter generation from natural language).
+- **Compat layer for `eco-helpers`** — `Compat::Pages` (`#each` cursor-paginated full iteration),
+  `Compat::Registers`, `Compat::FilterTranslator`, `Compat::PageReference`,
+  `Compat::StageCollection`, `Compat::StageView`, `Compat::SearchResults`, `Compat::Response`.
+- **Concerns** — `SnakeCamelAccess` (camelCase→snake_case delegation), `DataFieldAccess`,
+  `PageCompat`, `Deprecation`.
+- `Payload::OkPayload` base payload.
+- **Page read layer (Phase A)**
+  - `Fragment::PageFields` — named fragment on `BasePageInterface` covering identity, state,
+    lifecycle, and location fields. Includes `__typename` for union dispatch.
+  - `Interface::BasePage` — added `passboolean :draft` and `passthrough :externalId`.
+  - `Base::Page::Basic < Interface::BasePage` — concrete basic page class.
+  - `Base::Page::Phased` — `passarray :stages` (raw array until typed in Phase C).
+  - `Model::Page::Basic`, `Model::Page::Phased` — concrete model classes with class resolvers.
+  - `Model::PageUnion` — factory module: dispatches `.new(doc)` to `Basic` or `Phased`
+    based on `__typename`. Used as `item_class` / `node_class` throughout.
+  - `Connection::Page < Logic::Connection` — paginated page connection with `PageUnion` nodes.
+  - `Query::Page` (single page by ID), `Query::Pages` (paginated list), `Query::Templates`.
+  - `Model::Organization` — wired `query :page`, `query :pages`, `query :templates`.
+- **Page write layer (Phase B)**
+  - `Input::Page` — maps `PageInput` fields; owns `PAGE_FIELD_KEYS` as single source of truth.
+  - `Input::Page::Update` — maps `UpdatePageInput`; `from_model` builds the nested `page:`
+    sub-hash and always injects `patchVer` (a current `patchVer` must be fetched before update).
+  - `Input::Page::Archive`, `Input::Page::Unarchive`.
+  - `Mutation::Page::Update`/`Archive`/`Unarchive`, `Payload::Page::Update`/`Archive`/`Unarchive`
+    (all return a `PageUnion` item), `Builder::Page` (`update`/`archive`/`unarchive`),
+    `Ecoportal::API::GraphQL#page` top-level accessor.
+- **Fragment infrastructure**
+  - `Fragment::Pages` sub-namespace with `CommonPageUnion` — customer-facing fragment covering
+    stages, sections, all 20 data field types, actions, files, and emails. Parametric via
+    `$content`, `$only_content`, `$fields`.
+  - `FragmentDefinitions.register_namespace(klass)` — cross-namespace fragment discovery without
+    polluting the parent `fragments` hash.
+  - `BaseQuery#assemble_fragments` — resolves fragment spreads **recursively** (cycle-safe).
+- **`as_input` / diff pipeline**
+  - `Common::GraphQL::Model::AsInput#as_input(target_class:)` — delegates to a specified
+    `Input` subclass for field reshaping (e.g. `IdDiffInput` for array fields).
+  - `Logic::Input.from_model` — builds mutation input from a model diff; injects `patchVer`
+    and `clientMutationId`.
+  - `Input::ContractorEntity::Update.from_model` — reshapes array fields
+    (`associatedPeopleIds`, `leadContractorIds`) into `IdDiffInput` format.
+
+### Changed
+
+- **`Gemfile`** — override `graphlient` with the fork branch (GraphQL directives support).
+- **DataField dirty detection** — removed the per-field `@_dirty` flag in favour of
+  diff-based detection. `DataField` now uses a leaf-specific `DIFF_CLASS` (`LeafDiffService`)
+  so its `passarray` attributes are diffed inline instead of being stripped as cascaded keys.
+- **AI generator** — compatibility with the Anthropic Ruby SDK 1.x.
+
+### Fixed
+
+- **DataField array fields** (`Select`, `People`, `Checklist`, `ContractorEntities`,
+  `CrossReference`, `FileField`, `ImageGallery`) — were never reported dirty after a setter,
+  so `as_input` returned `nil`. `passarray` keys are *cascaded* attributes and the flat classic
+  diff strips them, expecting `diff_reduce` to re-add them by cascading into nested
+  `GraphQL::Model` children — but leaf-field arrays are plain hashes/strings, so they vanished.
+  Fixed with `DataField::LeafDiffService` (keeps cascaded keys) and by adding the missing
+  `array_ids` / `array_id_index` / `array_id_item` helpers to `HashDiffNesting`.
+- **Live AI specs** — resilient to SSL / auth failures in offline environments (skip instead of error).
+- **`HashDiffNesting#dig_path?`** — corrected to use `Hash#key?` rather than `respond_to?(:[])`,
+  preventing false positives on non-Hash objects.
+- **`DiffService#classic_diff`** — now returns a flat changed-prop hash (no `api_operation` /
+  `change_data` wrapper keys). `as_input` / `as_update` return `nil` when there are no changes.
+- **`assemble_fragments`** — fixed silent bug where a fragment referencing another fragment
+  (e.g. `PageFields → ...LocationNode`) would omit the referenced fragment from the query,
+  causing a server-side `unknown fragment` error.
+- **`Fragment.assemble`** — fixed silent bug where fragments defined in sub-namespaces
+  (e.g. `Fragment::Pages`) were never found, always returning empty.
+
+## [1.3.6] - 2026-06-05
+
+### Added
+
+- **`HttpClient#execute`**: new HTTP dispatch method — POSTs `{ query, variables, operationName }` as
+  JSON to `/api/:org_id/graphql` and returns the parsed response hash.
+- **`Common::GraphQL::ResponseError`**: typed exception raised when the GraphQL response body
+  contains an `errors` array.
+- **`Fragment.assemble(*syms)`**: class method that returns concatenated named fragment definition
+  strings for the given symbols, ready to append to a query document before dispatch.
+- **`Graphlient::Query#spread(name)`** _(graphlient fork)_: DSL helper that emits `...FragmentName`
+  in the query string. Replaces the `___Const` convention from graphql-client.
+- **`Client#to_query_string(&block)`** _(graphlient fork)_: builds a full GraphQL query document
+  from the DSL block and returns a `String` without touching Faraday or HTTP.
+
+### Changed
+
+- upgraded ecoportal upstream **gem** dependencies:
+  - `ecoportal-api`
+  - `ecoportal-api-v2`
+- **`BaseQuery#graphql_query`**: wired to the new dispatch path — builds query string via
+  `client.to_query_string`, appends needed named fragment strings, dispatches via
+  `client.http_client.execute`. Removes the graphql-client/Faraday dispatch path.
+- **`Common::GraphQL::Client`**: added `attr_accessor :http_client` to carry the HTTP dispatch
+  client alongside the DSL client.
+- **`Ecoportal::API::GraphQL#initialize`**: constructs and attaches a `Common::GraphQL::HttpClient`
+  instance to `@client.http_client`.
+- **Fragment strings**: all 7 fragment heredocs updated to use named fragment syntax
+  (e.g. `fragment Action on Action { ... }`), required for `Fragment.assemble` to emit
+  valid named fragment definitions.
+- **`FragmentDefinitions`**: stripped of `client.parse` and `namespace.const_set` — fragment
+  strings are now stored as plain Ruby strings. No longer depends on graphql-client for
+  fragment loading.
+- **Query/mutation blocks** (12 files): replaced `___Ecoportal__API__GraphQL__Fragment__X`
+  spread syntax with `spread :X` throughout all `default_block` and `default_payload_block` procs.
+
+### Fixed
+
+- **`HttpClient#base_request`**: added `request ||= HTTP` guard for the unmatched `@version` case
+  to prevent nil errors.
+- **`HttpClient#api_url`**: use `ENDPOINT_PATH` constant (`external/graphql`) consistently
+  instead of an inline hardcoded string.
+
+## [1.3.5] - 2026-05-26
+
+### Changed
+
+- Moved `graphql` endpoint to `external/graphql`
+- Missing env var (i.e. `ORG_ID`) will **raise** now an error (instead of just a print)
+
+## [1.3.4] - 2025-09-04
+
+### Added
+
+- Command execution result: **added** command doc when there's a `results` error.
+- Payload improvements:
+  - On `LocationsError.validationErrors`: fetch `property` property.
+  - On **results**, `Command` always fetch `__typename` and the other properties.
+
+### Changed
+
+- Changed base `error_doc`: **consistent property name**
+
+### Fixed
+
+- Correct fetch on `ok` (sometimes it is `null`: that doesn't mean failed).
+- **Consistent order** on `error?` and `error_doc`.
+- `Draft`
+  - **Overlapping** name `ConflictingIds` (vs `LocationsError.conflictingIds`)
+  - **Wrong** include on `FetchNested`
+
+## [1.3.3] - 2025-08-29
+
+### Added
+
+- Better error handling
+
+### Fixed
+
+- Unused parameter/variable `$includeArchivedNodes`
+
+## [1.3.2] - 2025-08-19
+
+### Added
+
+- `Mutation`: allow parameters other than **input**.
+- Location Structure `Draft` models
+- `Interface::LocationStructure::Nodes` for `LocationStructure` and `Draft::Structure`
+- `raw_response` as optional query parameter (for debugging)
+- `Logic::Input` (out of consistency)
+- Fragments:
+  - `LocationDraft`
+  - `LocationsError`
+- Query to include `draft` list when fetching an **RS**.
+- Location `Draft` queries:
+  - `Draft#byId`
+  - `Draft#create`
+  - `Draft#delete`
+  - `Draft#addCommands`
+  - `Draft#publish`
+  - `Draft#dropBadCommands`
+- Error tracking througout the payload models of location mutations
+
+### Changed
+
+- Upgrade dependency (`ecoportal-api` **gem**).
+- Moved rescue on fragment definition to `#define` itself.
+- `NodeInterface` moved to `Interface::LocationStructure::Node`
+- Code: Shorten namespace referral.
+- Swap to `Logic::BaseModel`
+- `Mutation` to introduce `:input` required parameter by using parent class.
+
+### Fixed
+
+- `QueryConnection`: bad code.
+- `conflictingIds` should be array.
+
+## [1.3.1] - 2025-06-11
+
+### Changed
+
+- upgraded gem dependencies
+- **Moded** `Ecoportal::API::GraphQL::Base::Model` to
+  - > `Ecoportal::API::GraphQL::BaseModel`
+- **Added** `Interface::LocationNode`
+- **Added** `Interface::BasePage`
+
+### Fixed
+
+- **Fragments**
+  - `Action` fragment to use `PageUnion` (**upgrade**)
+  - **Memoize** fragments.
+  - Add what fragment failed in the **error**.
+
+## [1.2.1] - 2025-05-16
+
+### Changed
+
+- upgrade `ecoportal-api` gem
+- upgrade `ecoportal-api-v2` gem
+
+## [1.1.1] - 2025-05-14
+
+### Added
+
+- `MemberChanges` helpers for `Base::ContractorEntity`
+- Custom **Diff** logic that can be used in GraphQL content:
+  - `Common::GraphQL::Model::Diffable::HashDiffNesting`
+    - Reused from `HashDiffPatch` (`ecoportal-api-v2`):
+      1. It does not use `patch_ver`, but rather just `id` property alone.
+      2. The _operation_ property has been renamed to `api_operation` (to ensure no collisions). And the operation types are symbols, and renamed to: `:delete`, `:update` and `:create`. This can show up to be useful when, for instance, reusing the output of `#as_update` to generate actual input objects (i.e. `#as_input`) that feed some GraphQL query.
+      3. The _data_ property has been renamed to `change_data`.
+      4. `Hash` **keys** are of type `Symbol`.
+  - `Common::GraphQL::Model::Diffable::DiffService`. In a GraphQL context, this aims to be able to implement a function called `#as_input` (equivalent to `#as_update`):
+      1. It uses the `HashDiffNesting` helpers.
+      2. It has capability to `ignore` certain keys.
+      3. It can calculate **diff** excluding nested models (i.e. those that are `root?` and, therefore, not part of the changed target model). This functionality is an optimization to `cascaded_callbacks` throughout the nested models.
+
+### Changed
+
+- `Common::GraphQL::Model::Diffable` by using `Diffable::DiffService` (with `cascaded_callbacks` implementation).
+  - `#as_update`
+  - `#dirty?`
+- upgraded `ecoportal-api` gem
+- updraded `ecoportal-api-v2` gem
+
+## [0.4.7] - 2025-04-02
+
+### Added
+
+- `page.id` to Action linked resources.
+
+## [0.4.6] - 2025-04-02
+
+### Added
+
+- `Ecoportal::API::GraphQL::Logic::QueryConnection`
+  - **Require** `default_connection_block` to child classes
+  - This aims to **not** having have client code having to define the block for `#each`
+
+### Changed
+
+- upgraded `ecoportal-api` gem
+- upgraded `ecoportal-api-v2` gem
+
+## [0.4.5] - 2025-03-14
+
+### Added
+
+- Query `actionCategories`
+- Mutation **create** `Action`
+
+### Changed
+
+- `Action` model to have `locations` (**RS** upgrade)
+
+## [0.4.4] - 2025-02-23
+
+### Changed
+
+- Upgraded `ecoportal-api` gem (maintanance)
+- Upgraded `ecoportal-api-v2` gem (to provision `root!` class method)
+- Defined some models that hand on their own as `root!`
+- Refactored `Base::Model` by moving its loggic to `Common::GraphQL`
+
+### Fixed
+
+- `Ecoportal::API::Common::GraphQL::HashHelpers`
+  - Truly make the iterator generic
+
+## [0.4.3] - 2024-11-21
+
+### Changed
+
+- upgrade gems
+  - `ecoportal-api`
+  - `ecoportal-api-v2`
+- `Ecoportal::API::Common::GraphQL::HttpClient.new` ceased to default `version` to `v1` (now it defaults to `nil`)
+
+## [0.4.2] - 2024-10-01
+
+### Changed
+
+- upgrade gems
+  - `ecoportal-api-v2`
+- add explicit dependency onto `ecoportal-api` gem (client)
+
+## [0.4.1] - 2024-08-09
+
+### Added
+
+- `ContractorEntity` added field `externalId`
+
+### Changed
+
+- gem upgrade `ecoportal-api-v2`
+
+## [0.4.0] - 2024-08-01
+
+### Changed
+
+- require `ruby 3`
+
+## [0.3.18] - 2024-05-16
+
+### Fixed
+
+- `Ecoportal::API::GraphQL::Payload::LocationStructure::CommandExecutionResult`
+  - Error is nullable
+
+## [0.3.17] - 2024-05-14
+
+### Fixed
+
+- `field_name` should add up to the path
+
+## [0.3.16] - 2024-04-29
+
+### Added
+
+- Exposed `graphql` `ContractorEntity` `destroy`
+
+### Fixed
+
+- incorrect loading
+
+### Changed
+
+- Input for ContractorEntity create moved as `update` (as it wasn't correct)
+
+## [0.3.15] - 2024-04-13
+
+### Added
+
+- `Ecoportal::API::GraphQL::Logic::BaseQuery`
+  - `::base_path` class instance var.
+- query to retrieve `currentOrganization.classifications`
+
+### Fixed
+
+- upgraded `ecoportal-api-v2` gem
+
+## [0.3.14] - 2024-03-13
+
+### Added
+
+- some benchmarking on
+  1. core graphql base `query`
+- `#parent_id` to location node model
+
+### Changed
+
+- upgraded `ecoportal-v2-api` gem
+
+### Fixed
+
+- Optimized `treeify` and locations structure class
+
+## [0.3.13] - 2024-02-03
+
+### Changed
+
+- upgrade `ecoportal-api-v2`
+
+## [0.3.12] - 2024-01-27
+
+### Added
+
+- Exposed `graphql` `Action` `update` and get a single `action`
+
+## [0.3.11] - 2023-09-19
+
+### Added
+
+- Exposed `graphql` `ContractorEntity` `create` and `update`
+
+## [0.3.10] - 2023-08-12
+
+### Fixed
+
+- `Ecopotal::API::GraphQL::Query::LocationStructure`
+  - `query` in basic_block missed an explicitly declared parameter.
+
+## [0.3.9] - 2023-08-03
+
+### Added
+
+- `Ecoportal::API::GraphQL::Logic::BaseQuery`
+  - Added support for **default** values.
+
+## [0.3.8] - 2023-07-18
+
+### Added
+
+- Integration for archiving actions.
+- `LocationNodeInterface` -> support for `classifications`
+- `Treeify` to dump more data per node (classifications)
+
+### Fixed
+
+- Silenced waning messages when redefining `Fragment`s
+
+## [0.3.7] - 2023-05-23
+
+### Fixed
+
+- `Ecoportal::API::Common::GraphQL::Client` adjusted `read_timeout` and `write_timeout` to `90` seconds.
+
+## [0.3.6] - 2023-04-17
+
+### Changed
+
+- Softened max version of **gem** dependencies
+
+### Fixed
+
+- `Ecoportal::API::GraphQL::Fragment#define` was not removing previous constants
+  - Changed check method to be `::const_defined?`
+
+## [0.3.5] - 2023-04-03
+
+### Fixed
+
+- `Ecoportal::API::GraphQL::Helpers::LocationsTree#treeify`
+  - Make it real id-case-insensitive (parents in lower case were being missed due to this)
+
+## [0.3.4] - 2023-04-03
+
+### Added
+
+- `Ecoportal::API::Common::GraphQL::AuthService`
+  - `#session_token` added **token auto-renew** functionality (when token expires in less than 90 minutes)
+  - `#session_token_renewed`
+
+### Fixed
+
+- Enabled to specify `host` (other than `live.ecoportal.com`) by the user
+
+## [0.3.3] - 2023-04-02
+
+### Fixed
+
+- `Ecoportal::API::GraphQL::Base::LocationNode` **added** attribute `archivedToken`
+
+## [0.3.2] - 2023-04-02
+
+### Changed
+
+- `Ecoportal::API::GraphQL::Helpers::LocationsTree#treeify` added support for `archived_token`
+
+## [0.3.1] - 2023-03-09
+
+### Changed
+
+- Upgraded core gem dependency `ecoportal-api-v2`
+
+## [0.2.3] - 2023-02-27
+
+### Fixed
+
+- Typo in tests LocationsStructures... should read `locationStructures`
+
+## [0.2.2] - 2023-02-24
+
+### Fixed
+
+- Build gem correctly
+
+## [0.2.1] - 2023-02-24
+
+### Changed
+
+- Migrate from TagTrees to **reporting structures** (breaking change)
+
+### Added
+
+- Basics for reporting structure mutations
+
+## [0.1.11] - 2022-11-29
+
+### Added
+
+- `Ecoportal::API::GraphQL::Base::Mutation`
+- Added `createContractorEntity`
+
+### Changed
+
+- **upgraded** `graphlient` gem dependency (support for framents)
+  - removed patch in this gem
+- Slight internal refactor of `Ecoportal::API::GraphQL::Base::Query`
+- Upgraded `ecoportal-api-v2` **gem** dependency
+
+## [0.1.10] - 2022-09-29
+
+### Changed
+
+- **upgraded** `ecoportal-api-v2` gem dependency
+
+### Fixed
+
+- Remove debugging message
+
+## [0.1.9] - 2022-09-26
+
+### Added
+
+- `Ecoportal::API::GraphQL::Query::TagTree`
+
+### Changed
+
+- **upgraded** `ecoportal-api-v2` gem dependency
+- added `Ecoportal::API::Common::GraphQL::QueryIntegration`
+  - restructured `Ecoportal::API::GraphQL::Model::Organization` class
+- **Patch** on `Graphlient::Query` for fragments support (**pull request**: <https://github.com/ashkan18/graphlient/pull/94>)
+
+## [0.1.8] - 2022-09-23
+
+### Added
+
+- `currentOrganization.tagTrees` query
+
+### Changed
+
+- **upgraded** `ecoportal-api-v2` gem dependency
+- Restructured the `Query` inheritance chain to make things simpler
+
+## [0.1.6] - 2022-09-19
+
+### Fixed
+
+- Call to **private** method `remove_const` in `Ecoportal::API::GraphQL::Fragment#define`
+
+## [0.1.5] - 2022-09-19
+
+### Added
+
+- Patch `GraphQL::Query#append_node` so we can use Fragments in blocks using `___` as start of the constant, and `__` for namespace separator
+  - Issue/feature request: <https://github.com/ashkan18/graphlient/issues/93>
+- `Ecoportal::API::GraphQL::Fragment#define` provided that client scripts can create their own fragments in their own namespace
+  - Exposed `Ecoportal::API::GraphQL#fragments`
+  - It will always (re)define in the `Fragment` root namespace
+
+## [0.1.4] - 2022-09-16
+
+### Fixed
+
+- Able to inject connection block to `each`
+- Error handling delegated to parent class (`QueryConnection`)
+- Retrieve `id` on elements of `Array`
+
+## [0.1.3] - 2022-09-15
+
+### Fixed
+
+- Fixed circular reference to `org_id` in `Ecoportal::API::Common::GraphQL::Client`
+
+## [0.1.2] - 2022-09-15
+
+### Changed
+
+- `Ecoportal::API::GraphQL` addded `email` and `pass` parameters on initialization
+  - This allows for integration in some client lib
+
+## [0.1.0] - 2022-09-15
+
+### Added
+
+- First commit with some basic structure