ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/projects/api-v2-to-graphql-migration/DECISIONS.md

@@ -0,0 +1,168 @@
+# Decisions — APIv2 → GraphQL Migration
+
+## 2026-06-04 — Bypass `graphql-client` for HTTP dispatch, retain DSL
+
+**Context:** `graphql-client` requires fragments to be parsed into Ruby constants, making
+fragment reuse across query helpers impossible for large models like Page.
+
+**Options considered:**
+1. Patch `graphql-client` to relax the constant requirement.
+2. Fork `graphql-client` fully and rewrite fragment handling.
+3. Bypass `graphql-client` for HTTP dispatch only; keep `graphlient` DSL for query building.
+
+**Decision:** Option 3 — bypass dispatch, retain DSL.
+
+**Reason:** Least invasive. The DSL value is in query construction, not request execution.
+A plain HTTP client posting `{ query, operationName, variables }` is sufficient and
+well-understood (matches Insomnia/Postman behaviour). Avoids a full fork maintenance burden.
+
+**Consequences:** Need to contribute a PR to `graphlient` fork allowing DSL-only mode
+(returns String without firing request). Fragment strings assembled manually before dispatch.
+
+---
+
+## 2026-06-04 — Fragment strategy: plain strings assembled at query time
+
+**Context:** `graphql-client` parses fragments into anonymous Ruby constants at load time,
+preventing reuse across multiple query helpers.
+
+**Options considered:**
+1. Define one mega-fragment constant per query (duplication, unmaintainable for large Page model).
+2. Use `graphql-client` anonymous fragments (current blocker).
+3. Define fragments as plain Ruby strings; append to query string before dispatch.
+
+**Decision:** Option 3.
+
+**Reason:** Simple, no gem dependency for fragment definition. Aligns with how the GraphQL
+server (graphql-ruby pro, persistent queries) already handles this server-side.
+
+**Consequences:** Fragment strings need to be validated once against schema. No dynamic
+introspection of fragment fields from client code (acceptable for now).
+
+---
+
+## 2026-06-05 — Fragment spread in query blocks: preserve custom block capability
+
+**Context:** The `___ConstantName` convention (graphql-client) is used inside both the gem's
+own `default_block` procs and any caller-supplied blocks (from end-scripts, `eco-helpers`,
+integration repos). Dropping graphql-client breaks this convention everywhere it is used.
+
+**Options considered:**
+1. Remove custom block capability entirely; provide a utility/DSL for custom queries instead.
+2. Preserve custom block capability; change the fragment-spread syntax and document the new convention.
+3. Preserve for now; accept a major version bump + clean break if the migration causes a
+   development loop.
+
+**Decision:** Option 2 as the starting point, with Option 3 as an explicit fallback.
+
+**Reason:** Custom blocks are rare in practice and were introduced before the author was
+fully fluent with GraphQL. However, removing them without a replacement utility would break
+the handful of integration repos that do use them. Preserving the capability with a new
+syntax is lower friction. If the `___Const` → new-syntax migration causes repeated
+back-and-forth complexity, a major version bump with a clean break (plus a utility/DSL
+replacement) is explicitly on the table.
+
+**Consequences:** The fragment-spread syntax inside all blocks (default and custom) changes.
+The new convention must be documented clearly and the change tagged as a major version bump.
+Custom block authors need to migrate; the number of affected sites is small.
+
+---
+
+## 2026-06-05 — `as_input` conversion ownership: input class, not model
+
+**Context:** When building a GraphQL mutation input from a model diff, something must
+own the logic of converting `as_update` output into the specific shape required by a
+given mutation input type. Two natural homes: the model (via `as_update(target_class:)`)
+or the input class (via `InputClass.from_model(model)`).
+
+**Options considered:**
+1. Model owns it: `model.as_update(target_class: SomeInputClass)` — model knows about
+   its input types.
+2. Input class owns it: `SomeInputClass.from_model(model)` — input class knows how to
+   interpret a model diff into its own shape.
+
+**Decision:** Option 2 — input class owns the conversion.
+
+**Reason:** The model should not need to know which mutation it is feeding. The cascade
+(`as_update` → nested `as_update`) still runs on the model side; the input class wraps
+it at the top and applies any structural reshaping needed for that specific mutation.
+Cleaner separation of concerns; easier to add new input types without touching model code.
+
+**Consequences:** Each mutation input class needs a `from_model(model)` (or equivalent)
+class method. The `as_input` instance method on the model becomes a convenience delegator
+to the resolved input class.
+
+---
+
+## 2026-06-04 — `as_update` diff: changed props only, no patch operations
+
+**Context:** APIv2 `as_update` builds a JSON Patch diff across nested models. GraphQL
+mutations target one model at a time and only need the final changed-property values,
+not patch operations. `patch_ver` is only required at the top level of a Page record.
+
+**Options considered:**
+1. Reuse APIv2 `as_update` as-is (produces wrong format for GraphQL).
+2. Add a `graphql:` mode flag to APIv2 `as_update`.
+3. Implement a separate `as_update` adapted for GraphQL in `ecoportal-api-graphql`.
+
+**Decision:** Option 3.
+
+**Reason:** Keeps GraphQL concerns in the GraphQL gem. Avoids coupling APIv2 model
+definitions to GraphQL-specific behaviour. Per-model override support (`as_update(target_class:)`)
+keeps it flexible for custom mutation input types.
+
+**Consequences:** Some duplication of diff logic vs APIv2, but the logic is simpler (no
+patch ops). Must maintain in parallel with APIv2 `as_update` for now.
+
+---
+
+## 2026-06-05 — Fragment spread syntax in DSL blocks: `spread :Name`
+
+**Context:** The `___Const` convention (graphql-client) is no longer viable after removing
+`graphql-client` from fragment parsing. A new syntax is needed for fragment spreads in
+both default and custom query/mutation blocks.
+
+**Options considered:**
+A. Add a `spread(name)` helper to `Graphlient::Query` (in the fork). Usage: `spread :Action`
+   emits `...Action` in the query string. DSL blocks remain fully functional.
+B. Drop the DSL block for selection bodies that contain fragment spreads; use heredoc strings
+   for those sections. More invasive; harder for custom blocks.
+
+**Decision:** Option A — add `Graphlient::Query#spread(fragment_name)`.
+
+**Reason:** Preserves the DSL convention. `spread :FragmentName` is readable and
+aligns with the existing `:Symbol` argument style throughout the query DSL. Custom
+blocks (from end-scripts, eco-helpers) only need the method name replaced — a mechanical
+change. Requires one small graphlient fork addition (already committed on
+`feature/dsl-only-mode` in the graphlient repo).
+
+**Consequences:**
+- All `___Ecoportal__API__GraphQL__Fragment__X` references in query/mutation blocks
+  replaced with `spread :X` (items 3.4).
+- Fragment heredoc strings must be named: `fragment X on Type { ... }` (item 3.5).
+- Fragment name = the Ruby symbol key (e.g., `:Action` → `...Action` → `fragment Action on ...`).
+- End-script and eco-helpers authors using custom blocks must migrate `___Const` → `spread :Name`.
+- Major version bump required when shipping (existing API decision from 2026-06-05).
+
+---
+
+## 2026-06-05 — HTTP dispatch client ownership: stored on Common::GraphQL::Client
+
+**Context:** BaseQuery needs both a DSL client (`to_query_string`) and an HTTP client
+(`execute`). Two options: pass both separately, or carry both on one object.
+
+**Options considered:**
+1. Pass `http_client:` as a separate argument to BaseQuery (changes constructor signature
+   and all callsites).
+2. Store `http_client` as an attribute on `Common::GraphQL::Client` (single entry point,
+   no callsite changes needed).
+
+**Decision:** Option 2 — add `attr_accessor :http_client` to `Common::GraphQL::Client`.
+Set from `Ecoportal::API::GraphQL#initialize` after constructing the graphql client.
+
+**Reason:** Minimal callsite changes. BaseQuery already receives `client`; adding
+`client.http_client` requires zero changes to how query/mutation objects are instantiated.
+
+**Consequences:** `Common::GraphQL::Client` holds a reference to `Common::GraphQL::HttpClient`.
+If the auth context changes, both clients need updating. Acceptable for now; can be
+refactored to a unified facade later.

data/.ai-assistance/projects/api-v2-to-graphql-migration/INTENT.md

@@ -0,0 +1,60 @@
+# Project: APIv2 → GraphQL Migration
+
+**Created:** 2026-06-04
+**Status:** active
+**Branch:** ai_dev_process
+**Target branch:** main
+
+## Goal
+
+Migrate ecoPortal integrations off the deprecated REST `/api/v2/pages` endpoint onto the
+GraphQL endpoint, by completing the `ecoportal-api-graphql` gem so it can serve as the
+primary client for page record queries and mutations — without requiring full rewrites of
+existing end scripts.
+
+## Motivation
+
+The `/api/v2/pages` endpoint has been deprecated and will be removed. All page-record
+integrations must move to GraphQL. The `ecoportal-api-graphql` gem exists for this purpose
+but has gaps: fragment reuse is blocked by `graphql-client` limitations, the HTTP client
+layer is incomplete, and the mutation input / diff model hasn't been fully designed.
+
+## Scope
+
+**In scope:**
+- Implement a standalone HTTP client in `ecoportal-api-graphql` that bypasses `graphql-client`
+  for request dispatch, while retaining the `graphlient` DSL for query/mutation building.
+- Solve the fragment reuse problem: define page model fragments as plain strings that are
+  assembled/appended at query time, not parsed into Ruby constants.
+- Design and implement the mutation diff model: adapted `as_update` that produces the final
+  changed-properties body (no patch operations, no nested diffs), with per-model override support.
+- Provide a DSL compatibility layer in `eco-helpers` so existing end scripts can swap to
+  GraphQL with minimal changes.
+- Contribute a PR to the `graphlient` fork to allow DSL usage without triggering a request
+  (returns query string only).
+
+**Out of scope:**
+- Migrating the actual end scripts themselves (that's downstream work).
+- Dynamic response model generation (desirable future state, not this project).
+- Full replacement of `graphql-client` — only bypass its request/fragment constraints.
+
+## Dependencies
+
+| Gem | Role | Location |
+|-----|------|----------|
+| `ecoportal-api` | HTTP client base | `c:\ruby_scripts\git\ecoportal-api\` |
+| `ecoportal-api-v2` | Model definitions (`DoubleModel`, `as_update`) | `c:\ruby_scripts\git\ecoportal-api-v2\` |
+| `graphlient` | GraphQL DSL (fork) | https://github.com/rellampec/graphlient |
+| `graphql-client` | GraphQL base (fork, to be bypassed for requests) | https://github.com/rellampec/graphql-client |
+| `eco-helpers` | **Downstream** consumer (uses this gem); DSL compat layer target | `c:\ruby_scripts\git\eco-helpers\` |
+
+Open upstream issue: https://github.com/ashkan18/graphlient/issues/114
+
+## Success Criteria
+
+- Page queries and mutations can be executed via `ecoportal-api-graphql` without
+  `graphql-client` handling the HTTP dispatch.
+- Fragment strings for the page model can be defined once and reused across queries.
+- `as_update` produces correct GraphQL mutation input bodies (changed props only, no patch ops).
+- Existing `eco-helpers`-based scripts require only minor adjustments to target GraphQL.
+- CI green, rubocop clean.

data/.ai-assistance/projects/api-v2-to-graphql-migration/TODO.md

@@ -0,0 +1,267 @@
+# TODOs — APIv2 → GraphQL Migration
+
+> Granulated during session 2026-06-04. Items are numbered for reference in discussion.
+> Natural implementation order: 1.1 → 2.1 → 2.2 → 3.1 → 3.2 → 3.3 decision → 3.4+3.5 → 2.3 → 4.x → 5.x → 6.x
+> Items 1.2, 6.1, and 6.4 are continuous throughout.
+
+---
+
+## Group 1 — `graphlient` fork: DSL-only mode
+
+- [x] **1.1** Add `to_query_string(**kargs, &block)` to `Graphlient::Client` (fork): builds the full
+  query document from the DSL block and returns a `String` — without touching Faraday/HTTP.
+  *Done 2026-06-05 — `graphlient/lib/graphlient/client.rb`, branch `feature/dsl-only-mode`*
+
+- [x] **1.2** Open a PR from the fork to upstream `ashkan18/graphlient` for the DSL-only mode change
+  (ref issue #114). *Done — PR #115 "Add DSL-only mode: to_query_string + spread" MERGED into
+  `ashkan18/graphlient` master (verified via `git ls-remote upstream` 2026-06-13). NOT yet released,
+  so still open to coordinated changes; we are the authors. See memory `project-fork-revival-strategy`.*
+
+---
+
+## Group 2 — HTTP dispatch layer in `HttpClient`
+
+- [x] **2.1** Add `execute(query_string, variables: {}, operation_name: nil)` to `HttpClient`:
+  POSTs `{ query:, variables:, operationName: }` as JSON to `/api/:org_id/graphql`, returns
+  the parsed response hash.
+  *Done 2026-06-05 — `lib/ecoportal/api/common/graphql/http_client.rb`*
+
+- [x] **2.2** Add response error handling in `execute`: surface GraphQL `errors` from the response
+  body as typed exceptions consistent with the existing `Ecoportal::API::GraphQL::Error` hierarchy.
+  *Done 2026-06-05 — raises `Common::GraphQL::ResponseError` for GraphQL errors, `Client::Error::UnexpectedServerError` for HTTP errors*
+
+- [x] **2.3** Wire dispatch end-to-end in `BaseQuery#graphql_query`:
+  (a) `client.to_query_string(&block)` builds query string,
+  (b) `assemble_fragments` scans for `...Name` and appends named fragment strings,
+  (c) `client.http_client.execute(full_query, variables: query_params)` dispatches,
+  (d) raw JSON hash returned → `wrap_response` navigates `data.*path`.
+  Decision: `http_client` stored as attr on `Common::GraphQL::Client` (see DECISIONS.md).
+  *Done 2026-06-05 — base_query.rb, common/graphql/client.rb, graphql.rb*
+
+---
+
+## Group 3 — Fragment plain-string strategy
+
+- [x] **3.1** Strip `client.parse` and Ruby constant assignment from `FragmentDefinitions#define`.
+  Fragment strings are already stored via `fragment :Sym, heredoc` — keep the storage, drop the parse step.
+  *Done 2026-06-05 — `lib/ecoportal/api/graphql/concerns/fragment_definitions.rb`*
+
+- [x] **3.2** Add `Fragment.assemble(*syms)`: returns concatenated fragment definition strings for the
+  given symbols, ready to append to a query string before dispatch.
+  *Done 2026-06-05 — `ClassMethods#assemble` in `fragment_definitions.rb`*
+
+- [x] **3.3** **Decision item** — resolved: Option A — `spread :Name` DSL helper in `Graphlient::Query`.
+  *Done 2026-06-05 — documented in `DECISIONS.md`; `spread` committed to graphlient `feature/dsl-only-mode`*
+
+- [x] **3.4** Update all existing query `default_block` procs to use `spread :Name`:
+  Action, Actions, ActionCategories, ContractorEntities, LocationStructure, LocationDraft, etc.
+  *Done 2026-06-05 — 12 query/mutation files updated*
+
+- [x] **3.5** Update all `Fragment::*` class definitions to use named fragment syntax.
+  *Done 2026-06-05 — 7 fragment files updated (e.g., `fragment Action on Action { ... }`)*
+
+---
+
+## Group 4 — `as_update` / `as_input` pipeline
+
+- [x] **4.1** Verify `DiffService` output for a realistic Page model: confirm no patch-op keys,
+  only changed prop values. Write/update the code-spec doc for this area.
+  *Done 2026-06-05 — `.ai-assistance/code/diff_as_input.md` written.*
+  *Finding: DiffService DOES produce patch-op keys (`api_operation`, `change_data`) at the top
+  level — this is wrong for GraphQL. Fix is part of 4.2/4.3 work. `patch_ver` is tracked on
+  `BasePage` via `passthrough :patchVer` but not yet injected in mutation input.*
+
+- [x] **4.2** Inject `patch_ver` at the top level in `AsInput#as_input`: read from the subject
+  model and include in the mutation input body. Currently not handled.
+  *Done 2026-06-05 — also fixed `DiffService#classic_diff` to return flat changed-prop hash
+  (no `api_operation`/`change_data` wrapper). `as_input` now returns nil when no changes.*
+
+- [x] **4.3** Implement `as_input(target_class:)` support: map diff output through a specified
+  `Input` subclass for key renaming / reshaping per mutation type (the "per-model override" pattern
+  from `DECISIONS.md`).
+  *Done 2026-06-05 — Logic::Input.from_model + AsInput#as_input(target_class:) +
+  ContractorEntity::Update override for IdDiff reshaping.*
+
+- [x] **4.4** RSpec specs for `DiffService` and `AsInput` covering: no-change → nil/empty,
+  single-prop change, nested model change, `root?` objects excluded, `patch_ver` present at top level.
+  *Done 2026-06-06 — 33 examples, 0 failures. Fixed: dig_path? Hash#key? check,
+  ContractorEntity::Update.from_model nil-diff + doc[] comparison, as_input_spec
+  Base::ContractorEntity + array field mutation via doc[].*
+
+---
+
+## Group 5 — `eco-helpers` DSL compat layer
+
+> Blocked on Groups 1–3 being functional.
+
+- [ ] **5.1** Audit the existing end-script API surface in `eco-helpers`: list the exact methods
+  scripts currently call against `ecoportal-api-v2` Page objects (fetch, update, create, etc.),
+  so the compat interface can be defined precisely.
+
+- [ ] **5.2** Design and implement a compat module in `eco-helpers` that proxies those methods
+  to the new GraphQL gem.
+
+- [ ] **5.3** Write a short migration guide for end-script authors.
+
+---
+
+## Group 6 — Validation & cleanup
+
+- [x] **6.0** Build a rubocop skill before writing any code: runs `rubocop --format json`
+  filtered to in-scope files, surfaces only actionable offences. Wire `rake spec` into
+  the same skill. `rubocop:disable` comments are handled by rubocop itself — the skill
+  does not need to second-guess them.
+  *Done 2026-06-05 — `.ai-assistance/skills/rubocop/SKILL.md`*
+
+- [ ] **6.1** Rubocop clean on all new/modified files — run continuously as work progresses,
+  not deferred to end.
+
+- [ ] **6.2** RSpec coverage for: `HttpClient#execute`, `Fragment.assemble`, and end-to-end
+  `BaseQuery#query` with stubs.
+
+- [x] **6.3** Manual integration test against `live.ecoportal.com` once dispatch is wired (after 2.3).
+  *Done 2026-06-05 — fetching reporting structure + Excel generation verified working.*
+  *Fixed during test: `ENDPOINT_PATH` constant in `api_url`, `request ||= HTTP` guard in `base_request`.*
+
+- [ ] **6.4** Update `DECISIONS.md` for any choices made during implementation (especially 3.3).
+
+- [ ] **6.5** Cycle-end Gemini review (see `project-cycle` skill).
+
+---
+
+## Group 7 — Fork packaging & portable test harness
+
+> Added 2026-06-27. Both items unblock day-to-day use of the revived forks and ongoing
+> backwards-compat validation ahead of the APIv2-cutover deadline (1 Jul 2026).
+> See memory `project-fork-revival-strategy`, `session-handoff-graphql-client-revival`,
+> `project-parity-test-plan`.
+
+- [x] **7.1** **Merged `graphql-client` revival branch + point the Gemfile at it.**
+  *Done 2026-06-27.* Built `integration/revival` on the fork (`rellampec/graphql-client`),
+  off `master`, cherry-picking the unique content of all four PRs in clean order (#79 base →
+  #80 docs → #81 char-tests → #82 parse fix) + a single `ci: pin i18n` commit (the four
+  branches each carried an identical copy). Applying #79 before #80 sidestepped the 1-line
+  CHANGELOG conflict. **Pushed; green:** 176 runs, 0 failures/errors, 4 skips; rubocop clean
+  (61 files). Wired into this gem via the **Gemfile** (not the gemspec — gemspecs can't carry
+  git sources; graphlient is a public gem we can't fork-point, so graphql-client is overridden
+  in the highest Gemfile we control). Commit `8827b2f`. **Reversible** — remove once the parse
+  fix ships upstream. `UPSTREAM.md` refreshed.
+  - ⏳ **Remaining (dev shell):** `bundle install` couldn't complete from the agent sandbox
+    (rubygems.org TLS interception — the git source itself fetched fine). Run `bundle install`
+    in your own shell to regenerate `Gemfile.lock` and confirm resolution, then a quick
+    `bundle exec rspec`.
+  - Upstream PRs stay OPEN — this branch is a convenience, not a substitute for merging.
+  - Mirror this for `graphlient` #116 only if needed (already fork-pinned separately).
+
+- [x] **7.2** **Portable `mini/automated-tests/` case folder (training repo).**
+  *Done 2026-06-27 (training repo, uncommitted pending dev).* Built a self-contained suite at
+  `mini/automated-tests/`:
+  - **Harness** (`lib/`): `asserter.rb` (pass/fail/skip recorder + green/red summary),
+    `test.rb` (base class + auto-registry via `inherited`), `fixtures.rb` (loads `fixtures.json`).
+  - **Runner** `automated_tests_case.rb` → CLI `-automated-tests` (one PASS/FAIL summary;
+    `-list`, `-only <Test>`, `-page-id`, `-fixtures` flags). Auto-loaded by one added line in
+    `mini/config/session.rb`.
+  - **Seed tests** (`tests/`): `org_read_test.rb` (auth smoke, no fixtures, env-agnostic) +
+    `field_dispatch_test.rb` (assertion-based evolution of `gql_read_probe_case.rb` — v2 `===`
+    dispatch on real fields).
+  - **(a) Portable** — org-specifics live only in `fixtures.json` (org_id pinned by `-mini`,
+    never embedded); `fixtures.example.json` + a documented 3-step port flow (copy folder →
+    edit fixtures → add one session.rb line). Missing fixture ⇒ test SKIPS, never fails.
+  - **(b) Reusable** — run against any gem branch (`pages`, released, fork-pinned per 7.1).
+  - **Verified offline**: harness wiring (registry/asserter/fixtures/runner) proven green via a
+    throwaway mock-graphql driver. **Live run is the dev's** (sandbox TLS-blocked to
+    `live.ecoportal.com`): `ruby main.rb -mini -automated-tests -page-id <all-21-fields ID>`.
+  Cross-ref `project-parity-test-plan`. Folder/convention doc: `mini/automated-tests/CLAUDE.md`.
+
+---
+
+## Group 8 — Cutover parity test coverage (live harness + gem specs)
+
+> Added 2026-06-28 after the page READ path went green live (8 gem bugs fixed; see
+> worklog 2026-06-28). READ + create-blank are validated; the WRITE/value/submit path
+> and the actual use cases are the remaining cutover risk. Live tests go in
+> `training/mini/automated-tests/tests/`; gem specs under `spec/`.
+> Memory: [[project-apiv2-cutover-usecases]], [[project-parity-test-plan]].
+
+- [x] **8.1** **Field value round-trip test** (`compat_v2/fields/values`) — HIGHEST VALUE,
+  entirely unexercised. create → set value → `updatePage` → re-read → assert persisted, per
+  type: PlainText/Number `value=`, Select `.select`/`.values`, People append, CrossReference
+  `.add`/`.clear`/`.reference_ids`. Several of these compat methods are flagged **missing** in
+  `project-apiv2-cutover-usecases` — this proves/exposes each and exercises the update path
+  (first time). Write-gated, on the seeded page.
+  *Done & LIVE-GREEN 2026-06-29 — PlainText/Number/Select/People (`people_ids`)/CrossReference
+  (`page_ids`/`reference_ids`) all round-trip. The P2 coded-but-untested array writes (People
+  `<<`, CrossRef `add`/`clear`) are now validated live; full mini suite 35/35.*
+- [x] **8.2** **`submit!` / stage completion test** — wires to `updatePage` task input
+  (see [[page-stage-submission]]); the cutover scripts call it.
+  *Done & LIVE-GREEN 2026-06-29. Root cause of the old stuck-stage failure: the stage has a
+  review-task config, so `completePageTask` ALONE enters "reviewing" and never advances. Fix =
+  `updatePage(submit: true, task: { completePageTask: { signOff: true } })` (inline sign-off
+  auto-approves the review). Gem gained
+  `Input::Page::Update.from_model(complete_page_task: { sign_off:, forced_complete:, notes: })`.
+  New test `compat_v2/page/submit_signoff_on_create` passes; old `stage_submit` flipped to the
+  confirmed call.*
+- [ ] **8.3** **Search test** — `registers.search` with `text_filter`/`options_filter`,
+  `get_by_name(name, type:)`, cans preview-dedup (`page_result.membranes` — search preview
+  exposes no field values).
+  *Partial 2026-06-29: FilterTranslator now translates `text_filter`→`match_filter` and
+  `options_filter`→`one_of`/`none_of` (commit 7725f96), and `get_by_name(type:)` landed
+  (2026-06-28). REMAINING = LIVE-validate the translated text/options filters against a real
+  `registers.search`, and the membranes dedup rework.*
+- [ ] **8.4** **BasicPage read test** — surfaces the known gap: `CommonPageUnion` has no
+  `... on BasicPage { sections }`, so basic pages get `corePageData` only.
+  *IN PROGRESS 2026-06-29 on branch `cutover/basicpage-sections`.*
+- [ ] **8.5** **Run the 3 prod use cases** (farmers / jamestrong / act-gov) against `mini` —
+  the ultimate parity, ideally A/B vs APIv2 per [[project-parity-test-plan]].
+  *Gap audit done + refreshed: `notes/cutover-usecase-gap-audit.md` (Update — 2026-06-29).*
+  Blockers BEFORE they can run, re-prioritized 2026-06-29:
+  **P0** — release/pin `pages` (HARD PREREQUISITE); farmers must include OozeRedirect (hits dead
+  v2 server today). ✅ **Phased write-path identity RESOLVED** (`stage.components` writes persist
+  via `updatePage`; `compat_v2/page/stage_write`). **P1** — ✅ `get_by_name(type:)` done;
+  ✅ `text_filter`+`options_filter` translated (now a LIVE-validation item, 8.3); cans `membranes`
+  dedup rework; eco-helpers `submit!` to pass `stageId` + map `force:`→`forced_complete:` (gem
+  supports it, draft in progress).
+- [ ] **8.6** **Gem RSpec regression specs** — the page-read path had ZERO coverage (8 bugs
+  lurked). Lock in: fragment-name assembly, DateTime sub-selection, `PageUnion` class dispatch,
+  `base_path` navigation, phased flatten/dedup, create `dataFields`. Use the `spec-generation`
+  skill.
+  *IN PROGRESS 2026-06-29 on branch `cutover/regression-specs-8-6`.*
+- [ ] **8.7** **Write/collection-level compat review** — single-element mutations forward via
+  shared doc refs; collection ops (add/remove/reorder fields, multi-section identity) need
+  review (the piece deferred from the 2026-06-28 phased flatten work). *Still outstanding 2026-06-29.*
+
+---
+
+## Group 9 — Template & field-structure edits (tests + the CSV/diff deliverables)
+
+> Added 2026-06-28 (dev). Tests for STRUCTURE edits (not just value writes), plus two
+> deadline-bearing deliverables. Behavioral precedent = the old one-off scripts under
+> `C:\ruby_scripts\implementation\orgs\*/config/ooze_cases` (multi-org-idle, multi_org_api):
+> `OozeSamples::RegisterUpdateCase` helpers — `with_target_stage`/`with_sections`/
+> `with_target_field`/`add_field(…, after:)`/`add_option`/`delete!`/`add_section`
+> (`components.add`/`add_component` ~120×, `add_section` ~23×). Backwards-compat with those
+> old scripts NOT required (nice-to-have). Memory: [[project-template-csv-pipeline]],
+> [[project-template-diff-deploy]], [[project-template-update-architecture]].
+
+- [ ] **9.1** **Page field-structure tests** — add / move (reorder) / delete a field on a
+  page via the GraphQL path; re-read and assert. Mirrors the most common past ops. Likely
+  exposes gem gaps (field add/delete + reposition via `updatePage` / WorkflowCommandInput).
+- [ ] **9.2** **Template edit tests** — create + update a template (add/edit/delete section
+  & field, set labels/options) via `Builder::Template#create/#update(commands:)`. Most
+  WorkflowCommandInput command types are unwrapped — this maps the gap.
+- [ ] **9.3** **CSV → templates pipeline** *(DEADLINE — see [[project-template-csv-pipeline]])*
+  — standard solution (eco-helpers?) to create/maintain ~300 templates from an input CSV
+  (sections/fields/labels columns). **Format agreed with customer ~mid-Jul; deliver Sept 2026.**
+  Identity: field id ← field internal **description**; section id ← a **hidden+deindex
+  PlainText marker field** (section external id) as the first field of each section. Needs
+  9.1/9.2 commands + a CSV→WorkflowCommandInput mapper.
+  *Design drafted: `notes/csv-template-pipeline-design.md`.* **First build step (also unblocks
+  the 9.2 "maintain" path): add `description` + `hideView` to the dataField read fragment
+  (`fragment/pages/common_page_union.rb` `dataFieldInterface`) + `passthrough` on
+  `Base::Page::DataField` — the identity scheme cannot pair fields/sections without reading
+  them back. Then a template-structure read entry-point (`Builder::Template` has no read).**
+- [ ] **9.4** **UAT→PROD diff-deploy** *(future — see [[project-template-diff-deploy]])* — a
+  deploy function applying a **UAT changelog** (not a raw snapshot diff) to PROD, preserving
+  PROD-only additions. Capturing UAT edits as the WorkflowCommandInput stream → replay on
+  PROD sidesteps the diff→command compiler. Page/template diff = nice-to-have for monitoring /
+  draft-from-diff.

data/.ai-assistance/projects/api-v2-to-graphql-migration/UPSTREAM.md

@@ -0,0 +1,53 @@
+# Upstream Dependencies — APIv2 → GraphQL Migration
+
+## graphlient (fork)
+
+**Remote:** https://github.com/rellampec/graphlient (fork of https://github.com/ashkan18/graphlient)
+**Required change:** DSL-only mode — allow a `graphlient` block to return the query String
+without triggering HTTP dispatch. See open issue: https://github.com/ashkan18/graphlient/issues/114
+
+**Approach:** Fork change + upstream PR contribution.
+**Status:** Pending — PR not yet opened.
+
+---
+
+## graphql-client (fork)
+
+**Remote:** https://github.com/rellampec/graphql-client (fork of
+`github-community-projects/graphql-client`)
+**Original migration need:** None — we bypass its HTTP dispatch layer and avoid the fragment
+constant requirement via the plain-string fragment strategy.
+**Revival effort (since 2026-06-13):** four upstream PRs are OPEN, awaiting a maintainer to
+approve the first-time-contributor CI run:
+- **#79** hygiene (CHANGELOG/CONTRIBUTING) — base
+- **#80** docs (stacked on #79)
+- **#81** characterization tests
+- **#82** parse-robustness fix (anchored regex; rspec+rubocop clean)
+
+**Status:** Revival in progress. Planned: merge all four into one fork branch (`integration/revival`)
+and source this gem's gemspec/Gemfile from it as a stopgap until upstream merges/releases — see
+TODO **7.1**. See memory `project-fork-revival-strategy`, `session-handoff-graphql-client-revival`.
+
+---
+
+## ecoportal-api-v2
+
+**Remote:** https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git
+**Local:** `c:\ruby_scripts\git\ecoportal-api-v2\`
+**Required change:** Per-model `as_update` override support (define behaviour per subclass
+rather than relying solely on the base path-diff). This has been partially added already.
+**Status:** In progress — confirm extent of existing implementation before adding more.
+
+---
+
+## eco-helpers (downstream — not upstream)
+
+> Note: `eco-helpers` is a **downstream** consumer of `ecoportal-api-graphql`, not an
+> upstream dependency. Changes here flow *down* to it, not up from it.
+> Tracked here for awareness; full scope documented in INTENT.md.
+
+**Remote:** https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git
+**Local:** `c:\ruby_scripts\git\eco-helpers\`
+**Required change:** DSL compat layer module so existing end scripts can target GraphQL
+with minimal edits.
+**Status:** Not started — design depends on `ecoportal-api-graphql` HTTP client being complete first.

data/.ai-assistance/projects/api-v2-to-graphql-migration/notes/csv-template-pipeline-design.md

@@ -0,0 +1,102 @@
+# Design — CSV → GraphQL Templates Pipeline (TODO 9.3)
+
+> Drafted 2026-06-28 (background design pass). Deliverable: a standard solution to
+> create + maintain ~300 templates for a customer from an input CSV (format agreed with
+> customer ~mid-Jul; delivery Sept 2026). Memory: [[project-template-csv-pipeline]],
+> [[project-template-update-architecture]].
+
+## Headline finding — the #1 gap to fix first (read side)
+
+The gem's command-bus foundation is solid: `Builder::Template#create(commands:)` /
+`#update(model, commands:, patch_ver:)` feed `WorkflowCommandInput[]`, and the structural
+section/field/option/stage commands are **already wrapped** (see §3). **But the identity
+scheme depends on reading back data, and the read fragments don't expose it:**
+
+- `fragment dataFieldInterface` (`fragment/pages/common_page_union.rb`) exposes only
+  `id, label, deindex, linkedFieldConfig` (+ per-type props) — **no `description`, no `hideView`**.
+- `Base::Page::DataField` (`base/page/data_field.rb`) `passthrough`s only `label, deindex, type`.
+
+Identity uses `description` (field key) and the hidden marker field (section key) — neither
+is currently readable. **FIRST BUILD STEP:** add `description` + `hideView` (and
+`hiddenOnMobile`) to `dataFieldInterface` and `passthrough :description, :hideView` on the
+base model. (Verify those are valid read fields on `DataFieldsInterface` — a re-run of the
+mini dispatch test will catch it if not, like the earlier fragment bugs.) Also needs a
+**template-structure read entry-point** (`Builder::Template` has no read method today).
+
+## 1. CSV schema (canonical internal model — adapt customer headers to this)
+
+One row per **field**; section identity repeated on each row (section implied by its rows).
+
+| Column | Purpose |
+|---|---|
+| `template_key` / `template_name` | external id (groups rows into a template) / display name |
+| `stage` | stage name/key (phased; constant default for single-stage) |
+| `section_key` | **external id of section** (→ hidden marker field, §2) |
+| `section_heading` / `section_layout` (`content`/`split`) / `section_order` | heading / layout / ordinal |
+| `field_key` | **external id of field** (→ field `description`, §2) |
+| `field_label` / `field_type` | label / type token (plainText, number, select, date, people, crossReference, …) |
+| `required` / `hidden` / `deindex` | per-field config |
+| `column` (0/1) / `field_order` | split-section side / ordinal (ordering via `moveField`) |
+| `options` (`Name:value|Name:value`) / `multiple` / `flat` | select config |
+| `tooltip` / `config_json` (escape hatch) | extra config |
+
+Keep additive/tolerant: unknown columns ignored, missing optionals defaulted. Write a thin
+**adapter** from the customer's headers to this model once their format lands.
+
+## 2. Identity / pairing
+
+- **Field id ← `description`.** After `addField` (no description arg), issue
+  `editFieldConfiguration(dataFieldId:, description: field_key)`. On maintain, read all fields,
+  map `description → dataFieldId`, pair CSV rows by `field_key` (match→update, none→add,
+  absent→delete-or-leave per config).
+- **Section id ← hidden marker field.** First field of each section = a hidden+deindex
+  PlainText whose `description` carries `section_key`. On maintain, read each section's first
+  component → `section_key → sectionId`. (Store key in `description`, not `value`, for uniform
+  extraction + safety if hide fails.)
+- **Create vs maintain.** Create: one ordered `commands:` array using `placeholderId`
+  cross-refs (addSection→addField(sectionId: placeholder)…), then `create(commands:)`.
+  Maintain: read → identity maps → diff desired-vs-actual → delta commands →
+  `update(model, commands:, patch_ver:)`. The **diff/keyed-pairing engine is the core**
+  (robust version of the v2 `unless get_by_name(...)` guards, keyed by stable ids not labels).
+
+## 3. CSV-row → WorkflowCommandInput mapping (all verified in COMMAND_MAP)
+
+| Op | Command(s) |
+|---|---|
+| add stage | `addStage` |
+| add section | `addSection` + `addStageSection` |
+| section heading / reorder / delete | `editSectionHeader` / `reorderSection` / `removeSection`(+`removeStageSection`) |
+| add field | `addField{placeholderId, fieldType, label, stageId, sectionId, column}` |
+| configure field (label, **description=id**, hideView, deindex, tooltip, byType config) | `editFieldConfiguration` |
+| move/reorder field | `moveField{id, sectionId, column}` |
+| delete field | `removeField` |
+| select options | `addSelectFieldOption` / `editSelectFieldOption` / `removeSelectFieldOption` |
+| per-type config | `editFieldConfiguration byType:` via the 12 `field_config/*` builders |
+
+## 4. Wrapped vs MISSING
+- **Wrapped/usable:** all structural commands above + 12 `field_config` builders;
+  `editFieldConfiguration` already has `description`/`hideView` as BASE_KEYS;
+  `Builder::Template#create/#update/#publish`.
+- **MISSING (build):** (1) **read-side `description`+`hideView`** on fragment + base model
+  [headline]; (2) **template-structure read entry-point** (hydrate stages→sections→fields +
+  patchVer, with `$fields`/`$content` flags); (3) **the pipeline** (CSV adapter → canonical
+  model → identity maps → diff → command builder → create/maintain/publish + retry); (4)
+  **verify `placeholderId`-as-reference** resolves server-side in one batch (else two-phase
+  create→read→configure); (5) hidden-marker helper/convention; (6) `Builder::Register` is a
+  stub — confirm whether templates are standalone or per-register.
+
+## 5. Open questions for the customer + risks
+- Headers + how sections are grouped; are `field_key`/`section_key` present or must we
+  synthesise stable keys (label-edit orphan risk if synthesised); phased vs single-stage;
+  in-scope field types; **delete semantics on maintain** (data-loss risk); auto-`publish` vs
+  leave drafts for review.
+- **Risks:** read-gap (high — de-risk first); `placeholderId` resolution (high — verify early,
+  have two-phase fallback); marker fragility (medium — `hideView`+`deindex`+`enableActions:false`,
+  treat missing marker as unknown→warn); `description` collides with human-visible descriptions
+  (use a sentinel prefix like `__key:`); scale/API volume (batch + patchVer-conflict retry);
+  `WorkflowCommandInput` is volatile → keep row→command mapping in ONE isolated translation layer.
+
+## Build order
+1. Read-side `description`/`hideView` + template-structure read. 2. Verify `placeholderId`
+   cross-ref. 3. Canonical model + CSV adapter. 4. Diff + command translator (isolated).
+   5. create/maintain/publish + retry. 6. Pilot on a few templates in `mini` before the 300 run.