ecoportal-api-graphql 1.3.13 → 1.3.16

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

@@ -1,240 +0,0 @@
-# GraphQL Domain Knowledge — Agent Reference
-
-*Accumulated from developer context, backend source code, and production Insomnia queries.*
-*This document is for AI agents. Read it before analysing or generating any GraphQL query or mutation.*
-
----
-
-## GraphQL is a Language — Not a Fixed REST Schema
-
-**Critical for agents:** GraphQL queries are client-defined. The same server resource can be
-queried in infinitely many ways — with different field selections, variable names, fragment
-compositions, and directive combinations. Variability between queries is **intentional and
-expected**, not an error. Do not assume a query "should look like" any specific previous example.
-
-Specific implications:
-- **Multiple operations per request** are valid GraphQL. A single HTTP request can contain
-  multiple `query` or `mutation` definitions, separated by blank lines. The server executes
-  them in declaration order. The `operationName` field in the JSON payload identifies which
-  named definition is the primary one. This is used when a stateless client middleware cannot
-  sequence separate requests (e.g. `ArchivePage` blanks `externalId` then archives, in one call).
-- **Fragment composition varies** — one team member's query may inline all fields; another's
-  uses the shared `CommonPageUnion` fragment. Both are correct.
-- **Variable names are arbitrary** — `$search`, `$searchConf`, `$conf` all refer to the
-  same `Search` argument type.
-- **Field selection is partial** — a query that omits `patchVer` is not wrong; it just
-  means the caller doesn't need it for that use case.
-
----
-
-## Backend Naming Conventions — Rosetta Stone
-
-The same concept appears under different names depending on which layer you're looking at.
-This causes confusion when reading source code alongside API output.
-
-| Concept | Backend Enzyme (old) | Backend NewEp (current) | APIv2 endpoint | GraphQL endpoint |
-|---|---|---|---|---|
-| Workflow phases | `stages` | `stages` | `stages` | `stages` |
-| Content containers within a stage | `flow_nodes` | `sections` | `sections` | `sections` |
-| Content fields within a section | `membranes` | `dataFields` | `components` | `dataFields` |
-
-**Note:** Enzyme is the original Rails backend namespace. NewEp is the revamp that the team
-is progressively migrating to. React front-end components that have been migrated to React
-use GraphQL; anything still on AngularJS uses the old APIv2. A model being available via
-GraphQL implies it has a NewEp backend class.
-
----
-
-## The Sorter `key` Field — aka `ref` — aka the Future Field ID
-
-The `key` field in searchConf sorters (and similarly in many filter params) is NOT the
-MongoDB `id` of the field. It is the **field's ES index key**, also called the `ref` property
-in the backend model (`Enzyme::Membrane` / `NewEp::DataField`).
-
-**Composition of `ref`:**
-```
-<type_shorthand>.<truncated_hash_of_label>
-```
-
-- `type_shorthand`: e.g. `date`, `gauge`, `files`, `select_str`, `select_num`,
-  `rich_text`, `plain_text`, `actions_list`
-- `.` separator
-- Hash of the label name (truncated when label > 3 characters)
-- Formula: `Ecoportal::API::Common::Content::StringDigest` in `ecoportal-api-v2`
-
-**Why this matters:**
-- This `ref` is how Elasticsearch identifies and indexes the field
-- It is used in: dashboard charts, filter configs, cross-register configs (linked fields,
-  visitor management), exports
-- A field's `ref` is stable as long as its label doesn't change
-- The team refers to this as the "Field ID" — a future project aims to formalise it as a
-  proper System ID (as opposed to the internal MongoDB `id`)
-
-**Known problem:** When tech scripts added fields to existing pages without copying from
-the template (e.g. bulk backfills), fields were created with random generation-time IDs
-rather than inheriting the template's `ref`. This creates duplicate/conflicting refs and
-causes issues in exports (missing CSV values) and some chart types.
-
----
-
-## The Genome Signature — ⚠️ IMPORTANT — Will Be Revisited
-
-**Record this carefully. This topic will be picked up again.**
-
-The genome signature is an identifier designed to pair fields across pages and their
-source templates. It enables knowing that "this field in page X is the same field as
-this field in template Y", even after the page was created, cloned, or restored.
-
-**Original use:** The `Migrator` Rails Service (under the Rails Services loadable path)
-had a full solution using the genome to pair fields during template changes and page
-restorations (backup to YAML + restore).
-
-**Current state (CORRECTED 2026-07-03 against the live schema — supersedes earlier claims):**
-- ✅ **IT IS EXPOSED IN GraphQL.** The live NewEp schema exposes **`genomeSignature: String`** on the
-  **`DataFieldsInterface`** and on **every concrete data-field type** (PlainText, Select, CrossReference,
-  People, Date, Number, Gauge, Checklist, TagField, Geo, Signature, ContractorEntities, ImageGallery,
-  File, Mailbox, ActionsList, Law, RichText, AiSummary, TableField, Chart, FrequencyRateChart,
-  EmbeddedStructure, PageAction). Verified in `.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json`.
-  APIv2 also exposed it. **This corrects the previous "NOT currently exploitable" claim, which was wrong.**
-- It is on **data fields only** (per the introspection) — not on sections/stages/pages.
-- **Our gem does not yet REQUEST it** — no fragment/model field. To use it: add `genomeSignature` to the
-  data-field fragment + `Base::Page::DataField`. (This is the real gap, not schema availability.)
-- **Not indexed** — the genome is not sent to Elasticsearch.
-- **Unreliable as a sole key** — see the failure modes (field re-use/re-purpose/revamp keep the same
-  genome for a different meaning; wrong for select options; etc.). Treat as a **strong-but-fallible
-  signal** in equivalence matching, never an unarguable key.
-- The Migrator solution (`app/services/migration/*`, `Migration::GenomeKindship`) was abandoned for
-  maintenance/coverage reasons, but its founding principle (data lives in data-fields) is valid.
-
-**Full treatment:** see `.ai-assistance/code/template_diff_pairing_domain.md` — the authoritative
-capture of the template diff/pairing/deploy problem space (lifecycle, failure modes, equivalence
-reframe, diff modalities, layering, pipeline, Product context).
-
-**Why it matters for the future:** The genome was the intended foundation for:
-- Automatically applying template changes to existing pages
-- Correctly pairing fields across page versions for cross-register configurations
-- The Field ID project (see above) may supersede or build on this concept
-
----
-
-## DataField Input — The `dataFields.updates` Structure
-
-When creating or updating page data fields via `createFromTemplate` or `updatePage`,
-field updates use a typed union pattern in `dataFields.updates`:
-
-```json
-{
-  "dataFields": {
-    "updates": [
-      { "date":      { "id": "FIELD_ID", "value": "2024-11-25T08:30+13:00" } },
-      { "people":    { "id": "FIELD_ID", "peopleIds": ["PERSON_ID"] } },
-      { "plainText": { "id": "FIELD_ID", "value": "JOB-0777" } },
-      { "richText":  { "id": "FIELD_ID", "content": "<p>HTML content</p>" } },
-      { "select":    { "id": "FIELD_ID", "options": [{ "id": "OPT_ID", "selected": true }] } },
-      { "geo":       { "id": "FIELD_ID", "address": "...", "coordinates": { "lat": -36.86, "lon": 174.76 } } }
-    ]
-  }
-}
-```
-
-The `id` in each field update is the **data field's MongoDB ObjectId** (from the built
-draft — obtained via `buildFromTemplate`), not the `ref`/Field ID.
-
----
-
-## Filter Rules — Silent Failure Traps
-
-**snake_case is mandatory for filter operations.** If a CamelCase operation name is used
-(e.g. `ExactFilter` instead of `exact_filter`), the server returns no error — it silently
-returns zero results. This is one of the hardest bugs to diagnose for customers.
-
-**`filters` should always be an Array.** The server normalises a single filter object to
-an array internally, so both formats work. However, always use the array form to be
-consistent and avoid edge cases.
-
----
-
-## Compound Mutations — Multiple Operations Per Request
-
-GraphQL allows combining multiple mutations in a single request. They execute in
-declaration order on the server. Use cases:
-
-1. **Stateless middleware:** When a client framework cannot maintain session state between
-   requests, combining dependent mutations into one request guarantees correct sequencing.
-   Example: `ArchivePage` blanks `externalId` first (to avoid duplicate ID conflicts on
-   unarchive+recreate), then calls `archivePage`.
-
-2. **Atomic-ish operations:** While GraphQL doesn't provide true ACID transactions, running
-   mutations in one request at least avoids partial state where a network failure between
-   two separate requests could leave data in an inconsistent state.
-
-The `operationName` field in the HTTP JSON payload names the primary definition. In a
-compound mutation, this is conventionally the name of the encompassing `mutation` block.
-
----
-
-## Template vs Instance Pages
-
-- **Template** (`templatesOnly: true` in org search): Source pages that define field
-  structure. Used with `buildFromTemplate` / `createFromTemplate` workflows.
-- **Instance page**: A page created from a template. Field IDs are assigned by the DB
-  on creation — they must be fetched (via `buildFromTemplate` result or subsequent org
-  search) before constructing field update inputs.
-- **`showHiddenData: Boolean`**: Controls whether fields marked as hidden in the template
-  are included in query results. Set to `true` for integration scripts that need all fields.
-
----
-
-## Stage Rendering: APIv2 vs GraphQL (critical)
-
-**APIv2:** Instance pages (pages WITH stages) are rendered and saved ONE STAGE PER REQUEST.
-`pages.get(id, stage_id: id)` returns a single-stage view. This was an architectural
-limitation. Templates and stageless pages are the only ones rendered in full by v2.
-
-**GraphQL:** Full page in one request. `page(id:)` returns all stages, all sections,
-all data fields the user has access to. Can update all stages at once, OR target a
-specific stage via `stageId: ID` in `UpdatePageInput`.
-
-**Stage-specific operations that REQUIRE `stageId`:**
-- Stage close-out / submit (triggers fill-in task creation on next stage)
-- Stage review sign-off (task completion triggers stage N+1 activation)
-- People fields scoped to a specific stage (permission grants are stage-scoped)
-Without `stageId`, these operations may succeed but not trigger the expected workflows.
-
-**Stage permissions in GraphQL:** No access errors — stages the user cannot access
-are simply absent from the response. APIv2 returned explicit errors per stage.
-Scripts that relied on stage-access errors need to check for stage presence instead.
-
-**Template updates:** Engineering explicitly does NOT want templates updated via GraphQL
-while the AngularJS template editor is still in use. Block template mutation endpoints.
-Read-only template queries (`templates(...)`) are fine.
-
----
-
-## Forces — Being Replaced by Workflow Builder
-
-**Forces** are AngularJS front-end snippets that attach to specific stages via bindings.
-They implement conditional field behaviour (show/hide sections, computed values, risk
-matrices). Forces are NOT accessible or meaningful via GraphQL. Low scripting priority.
-
-**Workflow Builder** (`pagesWorkflow`) is the replacement:
-- Deployed: notifications, automated page creation, task assignments
-- NOT yet deployed: conditional field/section workflows (show this section only when
-  field X has value Y; compute gauge value from severity × likelihood matrix)
-- Recently refactored — active development, high change velocity, quick CI/CD fixes
-- Do NOT design scripting against workflow builder internals — API is unstable
-
-**Implication for scripts:** Workflow triggers (task creation, stage transitions) fire
-as server-side side effects of `updatePage`. Scripts should check mutation payloads for
-unexpected errors, but should not attempt to directly manage workflow state.
-
----
-
-## Two Build Patterns — Legacy vs Standard
-
-**Build - Model (legacy):** Uses own inline fragment definitions per query. No shared
-`CommonPageUnion`. Still in use in some older Insomnia requests. Avoid in new code.
-
-**Build - Standard (current):** Uses `CommonPageUnion` with `$fields/$content/$only_content`
-variables. This is the team-wide standard — designed for customer-facing documentation
-and team knowledge sharing. New scripts should use this pattern.

data/.ai-assistance/code/refactoring/datafield-readwrite-shape-asymmetry.md

@@ -1,71 +0,0 @@
-# Review: DataField read/write shape asymmetry + dirty-detection baseline
-
-**Status:** OPEN — needs a thorough, dedicated review pass.
-**Raised:** 2026-06-30 (after a real bug found + fixed on `CrossReference`).
-**Owner cue:** Oscar flagged this for thorough review.
-
----
-
-## The bug class
-
-Several `DataField` subtypes are **READ** from the GraphQL response under one key/shape and
-**WRITTEN** (staged for mutation) under a *different* key/shape. This breaks two things:
-
-1. **Reading current values** — the typed reader reads the WRITE key, which the read response
-   never populates → returns `[]` (or stale) on a freshly-fetched page.
-2. **Dirty detection** — the default leaf diff compares `doc` vs `original_doc` at the key
-   level. A write adds a brand-new key (e.g. `pages`) absent from the read shape, so the field
-   looks dirty the moment any setter runs — even when the effective value is unchanged
-   (e.g. `clear` on an already-empty reference → phantom `referenceIds: []`). Under APIv2 the
-   equivalent no-op was correctly not-dirty; this is a v2-parity regression.
-
-## Per-field audit (2026-06-30)
-
-| Field | READ (fragment `common_page_union.rb`) | WRITE key | Reader reads | Verdict |
-|---|---|---|---|---|
-| `CrossReference` | `references { nodes { id … } }` | `pages` | refs→pages | **FIXED** (set-based `dirty?` vs `original_doc`; shared `ref_ids_from`) |
-| `FileField` | `items { fileContainer { id … } }` | `fileContainers` | `fileContainers` | **BROKEN reader** (reads key the response never has → `[]`) + phantom-dirty |
-| `ImageGallery` | `images { downloadUrl, caption … }` (no `id` even fetched) | `fileContainers` | `fileContainers` | **BROKEN reader** + phantom-dirty; read fragment also omits ids |
-| `ContractorEntities` | `contractorEntities { id, name … }` | `contractors` | `contractors` | **BROKEN reader** + phantom-dirty |
-| `TagField` | `locations { …locationNode }` | `locations` | `locations` | key matches, but write narrows shape (`{id,name,…}`→`{id}`); `as_input` is nil (page-level locations) → low impact, still verify |
-| `People`, `Select`, `Checklist`, `PlainText`, `RichText`, `Number`, `Gauge`, `DateField`, `Geo` | read key == write key | same | same | OK (no asymmetry) |
-
-## Recommended review/fix direction
-
-Two layers, decide per field:
-
-- **Reader correctness:** make `*_ids` read the actual response key (`items[].fileContainer.id`,
-  `images[].id` (needs the fragment to fetch it), `contractorEntities[].id`) — falling back to
-  the staged write key when present (so post-write reads reflect the staged value). The shared
-  `ref_ids_from(doc)` pattern in `cross_reference.rb` is the template.
-- **Dirty baseline:** any custom `dirty?`/`as_input` MUST diff the effective value against
-  **`original_doc`** (the diff `prev_doc` — see `Diffable::ClassicDiffService#prev_doc`), NOT
-  `doc`. Better still, where shapes can be normalised, defer to the inherited `DiffService`
-  rather than hand-rolling. Add a `consolidate!`-cycle assertion to every such field's spec
-  (read → mutate → as_input → `consolidate!` → re-check `dirty? == false`).
-
-These fields are NOT exercised by the 3 cutover use cases (toocs = CrossReference + People;
-cans = PlainText + Number + Select), so this is not a 1-Jul blocker — but it is a real
-correctness gap for full parity and any script touching files/images/contractors.
-
-## Retro — why the `CrossReference` bug went unnoticed (so we don't repeat it)
-
-1. **Hand-rolled the baseline from `doc` instead of `original_doc`.** I wrote a custom `dirty?`
-   from first principles instead of reading the existing diff contract first. Had I checked
-   `ClassicDiffService#prev_doc` (returns `original_doc`) before writing it, I'd have used the
-   right baseline. Root cause: built a new abstraction parallel to an existing one without
-   consulting it.
-2. **Incidental-correctness masked it in tests AND live.** My reader and my baseline both read
-   `references.nodes` from `doc`; since the setter only writes `pages`, the two always agreed on
-   the fetch-then-mutate path — the only path the specs and the live run exercised. The error is
-   invisible until `consolidate!` puts `pages` into `original_doc`.
-3. **No lifecycle (`consolidate!`) test.** The test matrix covered read→mutate but not
-   read→mutate→update→consolidate→re-diff, where the bug actually surfaces.
-4. **Conflated "read key isn't mutated" with "doc == baseline".** True premise, wrong
-   conclusion. Fragile coupling to current setter behaviour.
-
-**Guardrails going forward:**
-- Never compute a dirty baseline from `doc`; use `original_doc` or the `DiffService`.
-- Every field with a staged-write setter gets a `consolidate!`-cycle spec.
-- When adding a typed field, cross-check the fragment READ key against the setter WRITE key;
-  if they differ, normalise reads and baseline dirty on `original_doc`.

data/.ai-assistance/code/refactoring/opportunities.md

@@ -1,251 +0,0 @@
-# Refactoring Opportunities
-
-Low-priority items noted for future consideration. Not blocking current work.
-
----
-
-## [LOW] Review graphlient DSL for future method chaining support
-
-**Logged:** 2026-06-13
-**Upstream repo:** `C:\ruby_scripts\git\graphlient` — branch `feature/directives-dsl-support`
-
-**Context:** The current graphlient DSL passes directives as arguments:
-```ruby
-spread :InvoiceFields, _skip(if: :skip_invoice)
-on(:DraftInvoice, _skip(if: :skip_drafts)) { draft_id }
-```
-
-A fluent chain-style equivalent (`spread(:InvoiceFields).skip(if: :x)`) would require
-DSL methods to return a builder object rather than appending to `@query_str` and returning
-`nil`. The current approach (directives as arguments) does **not block** future chaining —
-both can coexist as alternative interfaces.
-
-**Before the next graphlient upstream PR:** verify no API decisions in the current MR
-force a hard dependency on the argument-passing style that would make a chain builder
-impossible to introduce later without a breaking change.
-
-**When to revisit:** When MR #116 is merged upstream. Low urgency — chaining is optional,
-current syntax is functional.
-
----
-
-## [LOW] Fragment definitions as `.graphql` files instead of Ruby HEREDOCs
-
-**Logged:** 2026-06-05
-**Files affected:** `lib/ecoportal/api/graphql/fragment/*.rb`
-
-**Idea:** Define named fragments in `.graphql` files (e.g.
-`lib/ecoportal/api/graphql/fragment/action.graphql`) and load them at startup via
-`File.read`, rather than embedding them as Ruby HEREDOCs.
-
-**Benefits:**
-- GraphQL files get syntax highlighting and editor tooling (linting, autocomplete).
-- Cleaner separation — `.graphql` is the DSL, `.rb` is the Ruby wrapper.
-- Easier to diff fragment changes in git without Ruby noise.
-
-**Open questions / why it's low priority:**
-- HEREDOCs work fine and there is no string interpolation in fragments, so the
-  only gain is cosmetic/tooling.
-- Client scripts may define custom queries as HEREDOCs in their own code. Whether
-  those should auto-load into the fragment registry (and how) is unresolved.
-  `FragmentDefinitions.assemble(*syms)` only knows about fragments registered via
-  `fragment :Sym, string` — any `.graphql` file loader would need to register them
-  the same way.
-- Until the auto-loading story for custom script fragments is clear, standardising
-  on `.graphql` files for the gem's own fragments may create inconsistency.
-
-**When to revisit:** Once there is a concrete script use case that benefits from
-`.graphql` file loading, or when editor tooling for HEREDOCs becomes a pain point.
-
----
-
-## [MEDIUM] Upstream-stack friction points — candidates for future graphql-client / graphlient MRs
-
-**Logged:** 2026-06-16
-**Scope:** `graphql-client` (fork: `rellampec/graphql-client`) and `graphlient` (fork: `rellampec/graphlient`)
-**Origin:** Adoption-friction analysis while documenting inline named fragments (graphql-client
-issue [#76](https://github.com/github-community-projects/graphql-client/issues/76)).
-
-These are the genuine reasons a large Ruby shop tends to avoid or rip out the
-`graphlient → graphql-client → graphql-ruby → faraday` stack. None is confirmed as the
-cause of any specific org's removal (see note below); they are the real ergonomic/architectural
-frictions worth addressing if we want the forks to be community-scalable.
-
-1. **Layered indirection for an HTTP POST.** Four abstraction layers to send a query string
-   and parse JSON. *MR angle:* keep graphlient a genuinely thin, optional convenience layer;
-   don't deepen coupling. Make the "drop graphlient, use graphql-client directly" path easy.
-
-2. **Heavy/opinionated dependency footprint.** graphql-client pulls in **ActiveSupport**
-   (only for `constantize`/Inflector at `lib/graphql/client.rb:161`) and the *full*
-   **graphql-ruby** gem to act as a client. *MR angle:* scope down the ActiveSupport surface
-   (the Inflector use is small and replaceable) — a frequent complaint for client-only use.
-
-3. **Design-philosophy mismatch — forced component isolation.** The constant-bound,
-   colocated-fragment model raises `ImplicitlyFetchedFieldError` on reuse-only fragments.
-   This is exactly issue #76. *MR angle:* the inline-named-fragment convention (documented)
-   + the planned anchored-regex parse fix together give a sanctioned "fragments for pure
-   reuse" path. Land both.
-
-4. **Client-side schema coupling.** Parse-time validation needs a vendored schema artifact
-   kept in sync with the server. *MR angle:* document/support a dynamic-query path
-   (`allow_dynamic_queries`) clearly so teams that build queries at runtime aren't forced
-   into static constants.
-
-5. **Maintenance / bus-factor optics.** graphlient last released 0.8.0 (Jan 2024); graphql-client
-   moved to the low-staff `github-community-projects/` org. *MR angle (non-code):* CHANGELOG +
-   CONTRIBUTING hygiene (already in flight on `chore/add-changelog-contributing`) and steady,
-   well-scoped PRs are the cheapest way to improve adoption confidence.
-
-6. **Parse-step robustness.** The unanchored `str.match(/fragment\s*#{const_name}/)` heuristic
-   at `lib/graphql/client.rb:161` misfires on prefix collisions (`...UserFields` vs
-   `fragment UserFieldsExtended`) and `\s*` even matches `fragmentUserFields`. *MR angle:*
-   the planned **Step 5** anchored fix (`fragment\s+Name\s+on\b`), stacked on the
-   characterization specs. Note upstream tried + reverted a fix here once (`c576c2e` →
-   `b5a4612`), so characterization-first is the right order.
-
-**Note on the "GitLab removed it" premise:** a GitLab.com group search for `graphql-client`
-MRs (2026-06-16) surfaced **dependency *updates*, not removals** — e.g. triage-ops bumping
-graphql-client to `~> 0.26.0` (merged Feb 2026). i.e. GitLab appears to actively maintain the
-dep, the opposite of dropping it. Treat the rendered search as indicative only (may be
-login-gated/partial); no verified evidence of a major-org removal exists. ecoPortal's own
-CI/CD removal was an internal decision, not an industry trend. See memory
-`project-fork-revival-strategy`.
-
-**When to revisit:** Items 3 & 6 are active (the #76 docs MR + Step-5 fix). Items 1, 2, 4 are
-future upstream MRs once the fork-revival sequence (hygiene → characterization → parse fix) lands.
-
-**Update (2026-06-16):** the fork-revival PRs are OPEN upstream — graphql-client #79 (hygiene),
-#80 (inline-fragment docs), #81 (characterization tests), #82 (the anchored parse fix). #82
-verified RuboCop-clean + tests green locally. See memory `session-handoff-graphql-client-revival`.
-
----
-
-## [LOW] graphql-client 1.0 (#15) — aligned contribution candidates
-
-**Logged:** 2026-06-23
-**Upstream:** `github-community-projects/graphql-client` issue
-[#15](https://github.com/github-community-projects/graphql-client/issues/15) (1.0.0 roadmap,
-rmosolgo, Feb 2024). Triggered by our #76 comment pinging the maintainer.
-**Priority:** LOW for us — opportunistic, only as the fork-revival PRs (#79–#82) progress.
-
-**State of the #15 roadmap (verified 2026-06-23 via issue + comments):** rmosolgo listed three
-pre-1.0 items and invited community suggestions ("If anyone has other suggestions for 1.0, please
-share them in a comment below").
-
-1. **Performance audit** (view helpers + runtime) — rmosolgo reported "performance audit work"
-   complete (Nov 14 2024). No formal closure; the runtime hot path includes `Client#parse`.
-2. **Subscription support** — **STILL OPEN** (the one unaddressed 1.0 item), and **genuinely out of
-   our lane.** A brief 2026-06-23 detour considered that the upcoming ecoPortal webhooks feature
-   might use GraphQL subscriptions, but the Confluence draft settles it: webhooks are **outbound
-   HTTP POST** (Standard Webhooks / Ed25519), and the "subscription" there is just a
-   **webhook-registration entity** CRUD'd via ordinary mutations — NOT a GraphQL `subscription` root
-   type. So webhooks do not pull #15 item 2 into scope. The webhook-registration CRUD *is* in our
-   lane, but as plain queries/mutations in this gem once it hits the PROD schema — no upstream
-   graphql-client change needed. See memory `project-webhooks-subscriptions`. Revisit only if some
-   *other* future need exposes a real `subscription` root type.
-3. **Response metadata in HTTP results** — **DONE** via billybonks' PR #43 (rate-limit headers etc.);
-   rmosolgo closed the item Nov 14 2024.
-
-So the literal roadmap is mostly closed except subscriptions. The real opening is the maintainer's
-**open invitation for 1.0 suggestions** — a 1.0 is the semver moment to land convention/cleanup
-changes that overlap exactly with our aim. Candidate contributions, each already partly in flight:
-
-- **[in flight] Land the parse-robustness fix (#82) as a 1.0 correctness item.** Anchored
-  `fragment\s+Name\s+on\b` regex at `client.rb:161`. Touches the "runtime code" the perf audit
-  named; converts a crash into a clean `ValidationError`. Cheapest, most defensible 1.0 contribution.
-- **[in flight] Bless "fragments for pure reuse" as a documented 1.0 convention (#76 + #80/#81).**
-  Inline named fragments, Apollo-aligned, backwards-compatible (constant-bound isolation kept as the
-  opt-in boundary). A behaviour/philosophy clarification is best made at a 1.0 boundary — frame it
-  to the maintainer that way.
-- **[new] Scope down the ActiveSupport dependency.** graphql-client pulls full ActiveSupport for
-  `constantize`/Inflector around `client.rb:161`. A 1.0 is when you'd drop/loosen a heavy dep;
-  classic adoption-friction win (friction item #2 above). Spec out a small internal constantize or
-  a narrower require before proposing.
-- **[new] Document/support the dynamic-query path (`allow_dynamic_queries`).** Lets teams build
-  queries at runtime without static constants — pairs with the fragments work and the schema-coupling
-  friction (item #4 above). Likely docs + a small guard test.
-- **[new] Named operations.** Optional operation names for server-side logging / APM / persisted
-  queries — also the natural identifier subscriptions would need later, so it nudges item #2 forward
-  without committing us to transports. Couples with the graphlient named-query DSL
-  (`query(:GetInvoice)`) already noted in memory `project-graphql-client-redesign`.
-
-**Suggested action (low urgency):** once #79–#82 are merged, post a single comment on #15 offering
-the parse-fix + inline-fragment convention + ActiveSupport scope-down as concrete 1.0 suggestions,
-and noting subscriptions are out of our scope (we drive query/mutation over HTTP POST; ecoPortal's
-webhooks are outbound HTTP, not GraphQL subscriptions — see item 2). Do not post before the revival
-PRs land (keeps our credibility — ship the easy ones first).
-
-**When to revisit:** after graphql-client #79–#82 merge. See memories
-`project-fork-revival-strategy`, `session-handoff-graphql-client-revival`.
-
----
-
-## [MEDIUM] graphlient masks client-side graphql-client errors (lost `inner_exception`)
-
-**Logged:** 2026-06-16
-**Upstream repo:** `C:\ruby_scripts\git\graphlient` — fork `rellampec/graphlient`, branch `feature/directives-dsl-support`
-
-**Problem:** `lib/graphlient/client.rb` rescues `GraphQL::Client::Error` in both `parse` (L19-20)
-and `execute` (L41-42) and re-raises `ClientError, e.message` — passing only the message string.
-graphlient's base `Error#initialize(message, inner_exception = nil)` is built to carry the
-original, and `FaradayServerError` uses it correctly (`super(inner_exception.message, inner_exception)`),
-but these two rescues leave `inner_exception = nil`. Lost: the original error's class and the
-source-location backtrace graphql-client deliberately sets (e.g. `uninitialized constant X`,
-static-validation messages). Related inconsistency: `faraday_adapter.rb:73` passes the exception
-as the *message* arg, so it also leaves `inner_exception` nil.
-
-**Fix:** `raise Graphlient::Errors::ClientError.new(e.message, e)` (matches FaradayServerError).
-If the symptom is a *blank* message rather than a lost cause, also audit the
-`GraphQLError`/`ExecutionError#to_s` path (formats from `errors.details`, can render empty).
-
-**Note:** user recalls patching BOTH graphql-client and graphlient for this — so there may be a
-graphql-client-side aspect too (the #82 anchoring fix already converts one crash into a clean
-`ValidationError`). Own graphlient PR, separate from #115/#116. Test-first (repro spec asserting
-`inner_exception` populated). Full detail: memory `graphlient-error-masking`.
-
-**When to revisit:** after the #116 DSL work; or sooner if error opacity bites again during the
-template-update / Workflow* work.
-
----
-
-## [VERY LOW] Extract `SnakeCamelIndifferentAccess` into its own gem
-
-**Logged:** 2026-06-05
-**Origin:** `eco-helpers` — `lib/eco/data/hashes/sanke_camel_indifferent_access.rb`
-  (note: filename has a typo — `sanke` instead of `snake`)
-**Specs:** already exist in `eco-helpers` spec suite
-
-**Idea:** Extract `Eco::Data::Hashes::SnakeCamelIndifferentAccess` (and its dependencies
-`Eco::Data::Strings::SnakeCase`, `Eco::Data::Strings::CamelCase`) into a standalone gem.
-Then use it in `ecoportal-api-graphql`'s base model so that GraphQL response docs (stored
-internally in camelCase as the API returns them) are also accessible via snake_case Ruby
-methods — without a full key rename on every read.
-
-**What the module does:**
-Hash accessor that treats `fooBar` and `foo_bar` as the same key. Configurable preferred
-form (defaults to `:snake_case`). Operations: `get`, `set`, `merge!`, `each`, `slice`,
-`camelize_keys`, `snakeize_keys`, all case-indifferent. Uses round-trip conversion via
-`snake_case(camelCase) ↔ camelCase(snake_case)`.
-
-**Why this matters for the GraphQL gem:**
-Currently `ecoportal-api-graphql` models map every field explicitly via `passthrough`,
-`passboolean`, etc. using camelCase names matching the API (e.g. `passthrough :patchVer`).
-Ruby callers must use `model.patchVer`. With indifferent access, `model.patch_ver` and
-`model.patchVer` would both work without any change to the field declarations. This
-eliminates the Ruby style inconsistency that has been a known pain point for 4+ years.
-
-**Proposed gem name:** `hash_case_indifferent` or `camel_snake_hash` (TBD)
-
-**Work involved:**
-1. Extract module + string helpers + specs into new gem repo
-2. Add gem as dependency of `eco-helpers` and `ecoportal-api-graphql`
-3. Include in `Common::GraphQL::Model` (or `Logic::BaseModel`) so all model
-   instances support both `model.patchVer` and `model.patch_ver`
-4. Verify no regressions in downstream `eco-helpers` scripts that use camelCase access
-
-**Prerequisite:** `as_update`/`as_input` pipeline (Group 4) should be stable first,
-since that pipeline reads field values off models. Once indifferent access is in place,
-the diff/input code may need to handle both key forms for lookups.
-
-**When to revisit:** After Group 4 + Page model Phase A/B are stable. New project
-milestone, not a small refactor.