ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/code/data_fields.md

@@ -0,0 +1,242 @@
+# Data Fields — Code Spec
+
+*All 20 DataField types, access patterns, mutation input serialisation, and Collection API.*
+
+---
+
+## Overview
+
+Data fields are the form inputs within a page (rich content — not structural metadata).
+Each field is a live instance with a MongoDB ObjectId (`id`) assigned on page creation.
+
+All field types inherit from `Base::Page::DataField < Logic::BaseModel` and live in
+`lib/ecoportal/api/graphql/base/page/data_field/`.
+
+---
+
+## All 20 Field Types
+
+| GraphQL `__typename` | Ruby class | Writable | Input key |
+|---|---|---|---|
+| `PlainText` | `DataField::PlainText` | ✓ | `plainText` |
+| `RichText` | `DataField::RichText` | ✓ | `richText` |
+| `Date` | `DataField::DateField` | ✓ | `date` |
+| `Number` | `DataField::Number` | ✓ | `number` |
+| `Gauge` | `DataField::Gauge` | ✓ | `gauge` |
+| `Select` | `DataField::Select` | ✓ | `select` |
+| `Checklist` | `DataField::Checklist` | ✓ | `checklist` |
+| `TagField` | `DataField::TagField` | ✓ | `locationField` |
+| `People` | `DataField::People` | ✓ | `people` |
+| `Geo` | `DataField::Geo` | ✓ | `geo` |
+| `ContractorEntities` | `DataField::ContractorEntities` | ✓ | `contractorEntities` |
+| `CrossReference` | `DataField::CrossReference` | ✓ | `crossReference` |
+| `File` | `DataField::FileField` | ✓* | `file` |
+| `ImageGallery` | `DataField::ImageGallery` | ✓* | `imageGallery` |
+| `Signature` | `DataField::Signature` | — | — |
+| `Mailbox` | `DataField::Mailbox` | — | — |
+| `ActionsList` | `DataField::ActionsList` | — | — |
+| `Law` | `DataField::Law` | — | — |
+| `AiSummary` | `DataField::AiSummary` | — | — |
+| `Table` | `DataField::Table` | — | — |
+
+\* File and ImageGallery require a prior file upload to the REST upload endpoint to obtain
+`fileContainerIds`. See `projects/TODO.md` — "File upload" item.
+
+---
+
+## Dispatch
+
+`DataField.from_doc(raw_hash)` reads `__typename` (or `type` if already normalised) and
+returns the right subclass instance. Falls back to base `DataField` for unknown types.
+
+```ruby
+field = Base::Page::DataField.from_doc({ '__typename' => 'PlainText', 'id' => 'f1', 'value' => 'X' })
+# => #<DataField::PlainText ...>
+```
+
+---
+
+## Field Access on Page Models
+
+`Interface::BasePage` includes `Concerns::DataFieldAccess`, so all concrete page models have:
+
+```ruby
+page.field_collection      # → DataField::Collection (memoized)
+page.components            # → same (v2 compat alias)
+page.data_fields_updates   # → [DataFieldInput, ...] for dirty fields
+page.data_fields_additions # → [DataFieldInput, ...] for added fields
+page.data_fields_deletions # → [field_id, ...] queued for deletion
+page.data_fields_dirty?    # → Boolean
+```
+
+`Base::Page::Phased::Stage` also exposes `components` (via `sections.components`) for
+stage-level field access.
+
+---
+
+## DataField::Collection API
+
+```ruby
+coll = page.components
+
+# Read
+coll.get_by_type(:plain_text)     # → [DataField::PlainText, ...]
+coll.get_by_type('PlainText')     # → same (string also works)
+coll.get_by_name('Summary')       # → DataField::PlainText (case-insensitive)
+
+# Iterate
+coll.each { |f| puts f.label }
+coll.map(&:label)
+
+coll.doc                          # → [raw_hash, ...] (v2 compat)
+coll.empty?                       # → Boolean
+coll.length                       # → Integer
+
+# Mutations — updates (existing fields)
+field = coll.get_by_name('Summary')
+field.value = 'New text'
+coll.dirty_inputs                 # → [{ plainText: { id: 'f1', value: 'New text' } }]
+
+# Mutations — additions (new field instances from buildFromTemplate)
+coll.add(id: 'server_id', label: 'New Field', type: 'PlainText') { |f| f.value = 'X' }
+coll.dirty_additions              # → [{ plainText: { id: 'server_id', value: 'X' } }]
+
+# Mutations — deletions (remove field instances)
+coll.mark_for_deletion('f1')          # by ID string
+coll.mark_for_deletion(field_object)  # by field object (uses field.id)
+coll.dirty_deletions              # → ['f1']
+
+coll.dirty?                       # → true if any of the above have changes
+```
+
+---
+
+## Setter API per Type
+
+### PlainText
+```ruby
+field.value = 'text string'
+field.as_input  # → { plainText: { id:, value: } }
+```
+
+### RichText
+```ruby
+field.content = '<p>HTML</p>'
+field.value = '<p>HTML</p>'   # alias
+field.as_input  # → { richText: { id:, content: } }
+```
+
+### Date
+```ruby
+field.value = '2025-06-30T09:00:00+12:00'  # ISO8601
+field.as_input  # → { date: { id:, value: } }
+```
+
+### Number / Gauge
+```ruby
+field.value = 42.5
+field.as_input  # → { number: { id:, value: } }  or  { gauge: { id:, value: } }
+```
+
+### Select
+```ruby
+field.select_option('Active')         # select by name (deselects all others)
+field.select_option('o1')             # select by option id
+field.select_option('opt1', 'opt2')   # multi-select by id
+field.clear_selection
+field.selected_options                # → [{ 'id' =>..., 'name' =>..., 'selected' => true }]
+field.as_input  # → { select: { id:, options: [{ id:, selected: }] } }
+```
+
+### Checklist
+```ruby
+field.check('Step A')                  # check by label
+field.check('i1', checked: false)      # uncheck by id
+field.as_input  # → { checklist: { id:, items: [{ id:, checked: }] } }
+```
+
+### TagField (LocationField)
+```ruby
+field.location_ids = ['loc1', 'loc2']
+field.as_input  # → { locationField: { id:, locationIds: [...] } }
+```
+
+### People
+```ruby
+field.people_ids = ['person1', 'person2']
+field.value = ['person1']   # alias
+field.as_input  # → { people: { id:, peopleIds: [...] } }
+```
+
+### Geo
+```ruby
+field.address = '123 Main St, Auckland'
+field.coordinates = { 'lat' => -36.86, 'lon' => 174.76 }
+field.as_input  # → { geo: { id:, address:, coordinates: } }
+```
+
+### ContractorEntities
+```ruby
+field.contractor_entity_ids = ['ce1', 'ce2']
+field.value = ['ce1']   # alias
+field.as_input  # → { contractorEntities: { id:, contractorEntityIds: [...] } }
+```
+
+### CrossReference
+```ruby
+field.page_ids = ['page1', 'page2']
+field.as_input  # → { crossReference: { id:, referenceIds: [...] } }
+```
+
+### File / ImageGallery
+```ruby
+# Requires prior file upload — see TODO "File upload"
+field.file_container_ids = ['fc1', 'fc2']
+field.as_input  # → { file: { id:, fileContainerIds: [...] } }
+                # or { imageGallery: { id:, fileContainerIds: [...] } }
+```
+
+---
+
+## DataFieldOneToManyInput — Wiring to Mutations
+
+`Input::Page::Update.from_model(page)` automatically collects field changes:
+
+```ruby
+input = Input::Page::Update.from_model(page)
+# input[:dataFields] may contain:
+# {
+#   updates:   [{ plainText: { id:, value: } }, ...],  # dirty existing fields
+#   additions: [{ plainText: { id:, value: } }, ...],  # newly added fields
+#   deletions: ['field_id_1', 'field_id_2']            # fields queued for deletion
+# }
+```
+
+`build_data_fields` only includes non-empty keys — if only `updates` exist, only
+`updates` is present in the hash.
+
+---
+
+## Stage-Level Field Access
+
+```ruby
+page = graphql.pages.get(page_id)
+stage = page.stages['Risk Assessment']
+
+# All fields in the stage (flat, across sections)
+stage.components.get_by_name('Hazard Description').value = 'Exposure to...'
+
+# Section-by-section
+stage.sections.each do |section|
+  section.components.each { |f| puts "#{f.label}: #{f.value}" }
+end
+```
+
+---
+
+## Spec Coverage
+
+| File | Coverage |
+|---|---|
+| `spec/ecoportal/api/graphql/base/page/data_field_spec.rb` | All 20 type dispatch, dirty tracking, PlainText, RichText, Select, People, Checklist, Collection (get_by_type/name, dirty_inputs, add/additions, deletions) |
+| `spec/ecoportal/api/graphql/input/page/update_spec.rb` | from_model with dataFields.updates, additions, deletions |

data/.ai-assistance/code/dependencies.md

@@ -0,0 +1,151 @@
+# Code Spec: Dependency Map
+
+**Scope:** All upstream and downstream gem dependencies for `ecoportal-api-graphql` — remote URLs, fork relationships, collaboration status, and access notes. Local paths are developer-specific; see the section below on local setup.
+**Last updated:** 2026-06-02
+
+---
+
+## This Repo
+
+| Property | Value |
+|----------|-------|
+| Gem name | `ecoportal-api-graphql` |
+| Remote (origin) | https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-graphql.git |
+| Relationship | Target repo — all work happens here |
+
+---
+
+## Upstream Dependencies
+
+### ecoportal-api
+
+| Property | Value |
+|----------|-------|
+| Gem name | `ecoportal-api` |
+| Version constraint | `~> 0.10, >= 0.10.15` |
+| Remote | https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git |
+| Collaboration | **Team-managed** — we own this gem |
+| Key deps | `dotenv`, `elastic-apm`, `http`, `rate_throttle_client` |
+| Notes | Provides REST API base, authentication, org context, and the `Ecoportal::API::Common` namespace that this gem extends. |
+
+### ecoportal-api-v2
+
+| Property | Value |
+|----------|-------|
+| Gem name | `ecoportal-api-v2` |
+| Version constraint | `~> 3.3, >= 3.3.1` |
+| Remote | https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git |
+| Collaboration | **Team-managed** — we own this gem |
+| Key deps | `ecoportal-api`, `mime-types` |
+| Notes | REST API v2 layer. Required by the entry point (`api-graphql.rb`). Depends on `ecoportal-api` itself. |
+
+### graphlient
+
+| Property | Value |
+|----------|-------|
+| Gem name | `graphlient` |
+| Version constraint | `>= 0.8.0, < 0.9` |
+| Remote (our fork) | https://github.com/rellampec/graphlient.git |
+| Remote (upstream) | https://github.com/ashkan18/graphlient.git |
+| Collaboration | **Fork (active)** — we drive new features; upstream is `ashkan18/graphlient` |
+| Git workflow | **Feature branches off our fork's working branch** (`feature/directives-dsl-support`). We open PRs upstream when appropriate but are not required to. Do NOT commit directly to `master`. |
+| Key deps | `faraday ~> 2.0`, `graphql-client` |
+| Notes | Friendly wrapper around `graphql-client`. `Common::GraphQL::Client` inherits from `Graphlient::Client`. |
+
+### graphql-client
+
+| Property | Value |
+|----------|-------|
+| Gem name | `graphql-client` |
+| Version constraint | (via graphlient) |
+| Remote (our fork) | https://github.com/rellampec/graphql-client.git |
+| Remote (upstream) | https://github.com/github-community-projects/graphql-client.git |
+| Collaboration | **Fork (upstream-contribution only)** — we do NOT maintain this gem; upstream is `github-community-projects/graphql-client` |
+| Git workflow | **ALWAYS use a feature branch** (e.g. `feature/allow-named-fragment-access`). Changes are intended as upstream PRs to `github-community-projects/graphql-client`. NEVER commit to `master`. If unsure about the branch name or PR strategy, ask the developer before committing. |
+| Key deps | `activesupport >= 3.0`, `graphql >= 1.13.0` |
+| Notes | Low-level GraphQL HTTP + parsing library. Pulled in transitively via `graphlient` — not a direct dependency. Check `Common::GraphQL::Patches` for any monkey-patches applied on top. |
+
+### graphql-ruby
+
+| Property | Value |
+|----------|-------|
+| Gem name | `graphql` |
+| Version constraint | `>= 1.13.0` (transitive, via graphql-client) |
+| Remote | https://github.com/rmosolgo/graphql-ruby |
+| Collaboration | **No collaboration** — external, read-only reference |
+| Notes | Schema definition and execution engine. Used server-side by EcoPortal; client-side usage here is indirect. API reference: https://graphql-ruby.org |
+
+---
+
+## Downstream Dependencies
+
+### eco-helpers
+
+| Property | Value |
+|----------|-------|
+| Gem name | `eco-helpers` |
+| Requires this gem as | `ecoportal-api-graphql ~> 1.3, >= 1.3.4` |
+| Remote | https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git |
+| Collaboration | **Team-managed** — we own this gem |
+| Notes | Primary consumer of this gem. **Backwards compatibility with `eco-helpers` must be preserved.** When a change could break it, cross-reference its usage before committing. |
+
+---
+
+## Dependency Chain Summary
+
+```
+graphql-ruby          (rmosolgo — external, read-only)
+        ↓
+graphql-client        (our fork ← github-community-projects/graphql-client)
+        ↓
+graphlient            (our fork ← ashkan18/graphlient)
+        ↓
+ecoportal-api         (team-managed — gitlab.ecoportal.co.nz)
+ecoportal-api-v2      (team-managed — gitlab.ecoportal.co.nz)
+        ↓
+ecoportal-api-graphql ← THIS REPO
+        ↓
+eco-helpers           (team-managed — gitlab.ecoportal.co.nz)
+```
+
+---
+
+## Local Development Setup
+
+Local paths are **developer-specific** — do not hardcode them in shared docs.
+
+Each developer who works across multiple gems should clone the relevant repos and record their local paths in `.claude/local_paths.md` (git-ignored). See `.claude/local_paths.example.md` for the format.
+
+### Using local gem overrides with Bundler
+
+To point Bundler at a local clone instead of the published gem:
+
+```bash
+bundle config local.ecoportal-api      /your/path/to/ecoportal-api
+bundle config local.ecoportal-api-v2   /your/path/to/ecoportal-api-v2
+bundle config local.graphlient         /your/path/to/graphlient
+```
+
+Or add a `path:` entry in `Gemfile` during development (remove before committing):
+
+```ruby
+gem 'graphlient', path: '/your/path/to/graphlient'
+```
+
+### For AI agents working with local clones
+
+1. Check `.ai-assistance/local_paths.md` for this developer's local paths.
+2. If the file doesn't exist, the repos are not locally available — use the remote URLs for reference only (read via web fetch or ask the developer to clone).
+3. Never assume a specific local path exists — always check first.
+
+---
+
+## Upstream Change Decision Guide
+
+If a task requires changes in an upstream gem, the options are (confirm with developer before proceeding):
+
+1. **Local monkey-patch** — apply the fix from within `ecoportal-api-graphql` (see `Common::GraphQL::Patches`). Fast, contained, but temporary debt.
+2. **Fork change** — commit to our fork (for `graphlient` or `graphql-client`). Appropriate for lasting fixes we own.
+3. **New version** — for `ecoportal-api` or `ecoportal-api-v2` (team-owned), cut a new version. For external forks, optionally contribute back upstream.
+
+Document the decision in the active project's `DECISIONS.md`.

data/.ai-assistance/code/diff_as_input.md

@@ -0,0 +1,234 @@
+# Code Spec: `as_update` / `as_input` Pipeline
+
+**Scope:** `Common::GraphQL::Model::Diffable`, `Common::GraphQL::Model::AsInput`,
+`DiffService`, `ClassicDiffService`, `HashDiffNesting`
+**Last updated:** 2026-06-05
+
+---
+
+## What This Pipeline Does
+
+Models that include `AsInput` (via `Model < DoubleModel`) can:
+1. **Diff themselves** against their original document via `#as_update` → returns a Hash
+   of only the changed properties.
+2. **Convert that diff** to mutation input via `#as_input` → returns a Hash ready to be
+   passed as the `input:` variable to a GraphQL mutation.
+
+---
+
+## Class Hierarchy
+
+```
+Common::GraphQL::Model < Common::Content::DoubleModel
+  includes Diffable         → provides #as_update, #dirty?
+  includes AsInput          → provides #as_input, .as_input(hash)
+
+Diffable::DiffService < ClassicDiffService
+  includes HashDiffNesting  → change_diff, patch_update, patch_new, patch_delete, ...
+  includes HashHelpers
+
+Diffable::ClassicDiffService
+  includes HashDiffNesting
+  provides #diff, #classic_diff, #curr_doc, #prev_doc
+```
+
+---
+
+## Current Output Format of `DiffService#diff` — KNOWN ISSUE
+
+**`#as_update` calls `DiffService#diff` which calls `classic_diff(flat: true)`, which calls
+`change_diff(curr_doc, prev_doc)`.**
+
+`change_diff` routes through `patch_update` for any Hash that has an `:id` key, producing:
+
+```ruby
+{
+  id:            "abc123",
+  api_operation: :update,
+  change_data:   { name: "New Name", status: "active" }
+}
+```
+
+**This is WRONG for GraphQL mutations.** The GraphQL mutation input should be flat:
+
+```ruby
+{ id: "abc123", name: "New Name", status: "active" }
+```
+
+**Why it's wrong:** GraphQL mutation inputs (`UpdateActionInput`, `UpdatePageInput`, etc.)
+do not have `api_operation` or `change_data` fields — they expect changed properties directly
+at the top level alongside `id`.
+
+**Root cause:** `HashDiffNesting` was ported from `ecoportal-api-v2`'s `HashDiffPatch`.
+The v2 gem uses JSON Patch semantics (`api_operation`, `change_data`). GraphQL mutations
+do not — they use direct property assignment.
+
+**Decision (2026-06-04):** GraphQL `as_update` must produce changed-props-only output with
+no patch-operation wrapper. See `DECISIONS.md` ("as_update diff: changed props only").
+
+**Fix required (TODO 4.2/4.3):** Either:
+- Override `classic_diff` in `DiffService` to call `change_data(curr, prev)` directly
+  (returns just the changed fields, no wrapper), and re-add `id` separately; or
+- Have `AsInput#as_input` detect and unwrap the patch-op structure before building input.
+The preferred approach per the DECISIONS is to fix `DiffService` itself.
+
+### Nested objects
+
+`diff_reduce` cascades through nested model objects (those that respond to `#as_update`)
+and replaces the nested path in the result with each nested model's own `as_update` output.
+These nested diffs also currently produce `api_operation`/`change_data` wrappers if the
+nested object has an `id`.
+
+For GraphQL, nested arrays of objects with IDs (e.g. `locations`, `associatedPeople`)
+are expressed differently per mutation — sometimes as `[ID]` arrays, sometimes as
+`IdDiffInput` (add/remove deltas), sometimes as full nested input objects. The `InputClass`
+(per the `from_model` pattern, TODO 4.3) is responsible for reshaping nested diffs into
+the correct format for each mutation.
+
+---
+
+## `AsInput` Current Behavior
+
+### Instance method `#as_input(clientMutationId: '')`
+
+1. Calls `as_update` → gets the diff hash (currently with patch-op wrapper, see above).
+2. Calls `self.class.as_input(diff, clientMutationId: ...)`.
+
+### Class method `.as_input(hash, clientMutationId: '')`
+
+1. Deep-converts hash keys to symbols.
+2. Merges `clientMutationId:`.
+3. Calls `remove_nil_keys_deep(hash, target: :id)` — removes nil-valued `:id` keys
+   (keeps `id:` only when it has a value; removes nil ids from nested objects so they
+   don't confuse the server).
+
+**Current output (wrong):**
+```ruby
+{
+  id:            "abc123",
+  api_operation: :update,
+  change_data:   { name: "New Name" },
+  clientMutationId: ""
+}
+```
+
+**Desired output (target):**
+```ruby
+{ id: "abc123", name: "New Name", clientMutationId: "" }
+```
+
+---
+
+## `patch_ver` — Concurrency Control
+
+**Schema:** `patchVer: Int!` (non-null) on `BasePageInterface`. Present on all Page types.
+`BasePage` in the gem maps it as `passthrough :patchVer`.
+
+**How it works:**
+- Every Page response includes `patchVer` (an incrementing Integer).
+- On `UpdatePage` mutation, the caller may pass `patchVer:` (optional).
+- The server checks that the submitted `patchVer` matches the current value; if not,
+  the update is rejected (optimistic locking / last-write-wins prevention).
+
+**Current gap (TODO 4.2):** `AsInput#as_input` does not inject `patchVer` into the
+output. The subject model (`BasePage` subclass) holds `patchVer` via `passthrough :patchVer`
+but it is never extracted and included in the mutation input hash.
+
+**Fix required:** In `AsInput#as_input` (instance method), read `self.patchVer` if the
+model responds to it, and include it in the input hash at the top level:
+
+```ruby
+def as_input(clientMutationId: '')
+  diff = as_update  # TODO: once fixed, returns flat changed props
+  diff[:patchVer] = patchVer if respond_to?(:patchVer) && !patchVer.nil?
+  self.class.as_input(diff, clientMutationId: clientMutationId)
+end
+```
+
+---
+
+## `from_model` Pattern (TODO 4.3)
+
+**Decision (2026-06-04):** Conversion from model diff to mutation-specific input shape is
+owned by the `Input` class, not the model. Each mutation's input class implements
+`InputClass.from_model(model)`.
+
+**Why:** The model (`BasePage`, `Base::Action`, etc.) should not know which mutation it
+feeds. The input class knows its own schema shape (field names, nested structure, ID vs
+IdDiff arrays, etc.).
+
+**Pattern:**
+```ruby
+class Input::Action::Update < Logic::Input
+  def self.from_model(action_model)
+    diff = action_model.as_update  # after fixing: flat {name:, status:, ...}
+    new(
+      id:         action_model.id,
+      patchVer:   action_model.patchVer,  # if applicable
+      **map_fields(diff)
+    )
+  end
+
+  private_class_method def self.map_fields(diff)
+    # rename, reshape, filter fields as needed for this specific mutation input
+    diff.slice(:name, :description, :status, :dueDate, :assignedPersonMemberIds, ...)
+  end
+end
+```
+
+**The `as_input` instance method becomes a convenience delegator:**
+```ruby
+def as_input(target_class: default_input_class, **kargs)
+  target_class.from_model(self, **kargs)
+end
+```
+
+---
+
+## `root?` Objects in the Diff
+
+Models marked `root!` (via `Ecoportal::API::Common::GraphQL::ClassHelpers`) are excluded
+from cascaded diffs. These are typically "lookup" objects that are referenced but not
+owned — e.g. `Base::Organization` (root!), `Base::Action` (root!). Their nested presence
+in a model's JSON will not generate diff entries.
+
+This is correct behaviour: you don't diff a referenced Organization when updating a Page;
+you only diff properties the Page itself owns.
+
+---
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `lib/.../model.rb` | `Model < DoubleModel`, includes `Diffable` and `AsInput` |
+| `lib/.../model/diffable.rb` | `#as_update`, `#dirty?`, `DIFF_CLASS` |
+| `lib/.../model/diffable/diff_service.rb` | Main diff logic, `#diff`, `#diff_reduce` |
+| `lib/.../model/diffable/classic_diff_service.rb` | Base: `#curr_doc`, `#prev_doc`, `change_diff` dispatch |
+| `lib/.../model/diffable/hash_diff_nesting.rb` | `change_diff`, `patch_update/new/delete`, array diffing |
+| `lib/.../model/as_input.rb` | `#as_input`, `.as_input(hash)` class method |
+| `lib/.../interface/base_page.rb` | `passthrough :patchVer` — Page models carry this |
+
+---
+
+## Backend Reference (ecoPortal_master)
+
+- `app/graphql/types/pages/interfaces/base_page_interface.rb` — `patchVer: Int!` (non-null)
+- `app/graphql/mutations/pages/update.rb` — `argument :patch_ver, Integer, required: false`
+- `app/graphql/types/fill_in_page/inputs/page_input.rb` — Page update input fields:
+  `locations`, `other_tags`, `time_zone`, `state`, `task_priority`, `name`, `external_id`
+- `app/graphql/types/fill_in_page/inputs/data_field_input.rb` — DataField inputs (complex)
+
+**UpdatePage mutation shape:**
+```graphql
+mutation UpdatePage($id: ID!, $patch_ver: Int, $page: PageInput, $data_fields: [DataFieldInput], ...) {
+  updatePage(id: $id, patchVer: $patch_ver, page: $page, dataFields: $data_fields, ...) {
+    item { ...BasePageInterface }
+    errors { ... }
+  }
+}
+```
+
+Note: `id`, `patchVer`, and `page` (the input object) are separate top-level arguments —
+not nested under a single `input:` object like Action mutations. This is a structural
+difference that the `from_model` pattern must account for per mutation type.