ecoportal-api-graphql 1.3.5 → 1.3.9

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

@@ -0,0 +1,230 @@
+# 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:**
+- Mostly **unused** — the Migrator solution was abandoned due to maintenance cost and
+  low usage
+- **Not indexed** — the genome is not sent to Elasticsearch
+- **Unpaired on many pages** — tech scripts that added fields without copying from the
+  template introduced fields with random creation-time genome signatures, breaking the
+  pairing with the template
+- **NewEp port status:** Uncertain — unclear whether the NewEp namespace fully ported
+  the Genome functionality from the Enzyme namespace
+- The genome is NOT currently exploitable for scripting or integration purposes
+
+**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

@@ -0,0 +1,71 @@
+# 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

@@ -0,0 +1,251 @@
+# 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.