ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/projects/eco-helpers-compat/INTENT.md

@@ -1,244 +0,0 @@
-# Project: eco-helpers GraphQL Compat Layer
-
-**Created:** 2026-06-07
-**Status:** Starting — URGENT (APIv2 retires in ~3 weeks)
-
----
-
-## Goal
-
-Existing eco-helpers scripts work against `ecoportal-api-v2` (REST). They must continue
-to work against `ecoportal-api-graphql` (GraphQL) **without changing one line of script code**
-related to pages.
-
-The compat layer wraps `Ecoportal::API::GraphQL` and exposes the same interface that
-eco-helpers scripts currently call against `Ecoportal::API::V2`.
-
----
-
-## eco-helpers API Surface (audited 2026-06-07)
-
-### Pages
-
-| v2 call | Description | GraphQL equivalent |
-|---|---|---|
-| `apiv2.pages.get(id)` | Fetch page by ID | `Query::Page.new(client).query(id: id)` |
-| `apiv2.pages.get_new(template_id)` | Build draft from template | `Mutation::Page::BuildFromTemplate` (via `buildPageFromTemplate`) |
-| `apiv2.pages.create(page, from: template_id)` | Create from filled draft | `Mutation::Page::CreateFromTemplate` |
-| `apiv2.pages.update(page)` | Update changed page | `Mutation::Page::Update` with `Input::Page::Update.from_model` |
-| `apiv2.pages.get_body(page)` | Get patch doc of changes | `page.as_update` |
-
-### Registers / Search
-
-| v2 call | Description | GraphQL equivalent |
-|---|---|---|
-| `apiv2.registers.search(register_id, opts) { \|r\| }` | Paginated search | `Query::RegisterPreviewPages` (fast/ES) for existence; org search for full data |
-
-Search options v2 → GraphQL mapping:
-- `sort: 'created_at'`, `dir: 'asc'` → `SearchConf.new.sort(:created_at, :asc)`
-- `query: text` → `SearchConf.new.query(text)`
-- `filters: [...]` → `SearchConf` with appropriate filter objects
-
-### Page object API
-
-| v2 accessor | v2 type | GraphQL equivalent |
-|---|---|---|
-| `.id` | String | `Model::Page::Basic#id` |
-| `.state` | String | `#state` |
-| `.template_id` | String | `#sourceTemplateId` |
-| `.created_at` | String | `#createdAt` |
-| `.updated_at` | String | `#updatedAt` |
-| `.stages?` | Boolean | `#stages.any?` |
-| `.current_stage_id` | String | `Model::Page::Phased#currentStage.id` |
-| `.stages` | Collection | `#stages` |
-| `.stages.get_by_name(name)` | Stage | filtered stages |
-| `.sections` | Collection | stage `.sections` or BasicPage `.sections` |
-| `.components` | Collection | sections → dataFields (APIv2 name for fields) |
-| `.tags` | Array | `#otherTags` (or `#baseTags` for base tags) |
-| `.base_tags` | Array | `#baseTags` |
-| `.external_id` | String | `#externalId` |
-| `.validate` | String or nil | custom validation (not in GraphQL schema) |
-| `page.consolidate!` | void | `page.original_doc = page.doc.dup` (reset dirty tracking) |
-
-### Dirty state tracking
-
-v2 uses `dirty?(page)` which checks if `patch_doc(page)['page']` is non-empty.
-GraphQL uses `page.as_update` — returns nil if no changes, hash if changed.
-
-Equivalence:
-```ruby
-# v2
-dirty?(page)
-# GraphQL compat
-!page.as_update.nil?
-```
-
-### Response objects
-
-| v2 | GraphQL |
-|---|---|
-| `response.success?` | `payload.success?` |
-| `response.status` | `payload.error? ? :error : :ok` |
-| `response.body` | `payload.error_doc` |
-
----
-
-## Design: CompatPages and CompatRegisters
-
-Two wrapper objects that expose the v2-compatible interface:
-
-```ruby
-module Ecoportal::API::GraphQL::Compat
-  class Pages
-    def initialize(client); @client = client; end
-    def get(id, **kargs) = ...
-    def get_new(template_id) = ...
-    def create(page, from:) = ...
-    def update(page) = ...
-    def get_body(page) = page.as_update
-  end
-
-  class Registers
-    def initialize(client); @client = client; end
-    def search(register_id, options = {}, &block) = ...
-  end
-end
-```
-
-And on the top-level `Ecoportal::API::GraphQL` class:
-```ruby
-def pages     = Compat::Pages.new(client)
-def registers = Compat::Registers.new(client)
-```
-
-**Key constraints:**
-- `pages.get` must return an object that responds to all page accessors above
-- `pages.create` must return a reference object with `.page_id` and `.active_stage_id`
-- `page.consolidate!` must reset dirty state
-- `registers.search` must yield results in the same shape as v2 (block with `.id`)
-
----
-
-## Architectural Differences: APIv2 vs GraphQL (critical for compat)
-
-### Stage rendering and updating
-
-**APIv2:** Instance pages (pages with stages) are rendered ONE STAGE PER REQUEST.
-Every `pages.get(id, stage_id:)` call fetches a single stage view. Updating is also
-done per-stage. This is a known limitation.
-
-**GraphQL:** Fetches the full page in one request. Can update all stages at once via
-`updatePage`. Can also do stage-specific updates via `stageId` in `UpdatePageInput`.
-
-**Implication for compat:**
-- eco-helpers `RegisterUpdate` loops through stages by fetching each one. In GraphQL
-  compat, we fetch the full page once and let the script work on a client-side stage view.
-- Stage-specific submit (e.g. close-out stage N to trigger fill-in task on stage N+1)
-  STILL requires `stageId` in the GraphQL mutation. The submit trigger (creating/starting
-  the next fill-in task) is server-side logic keyed on `stageId`.
-- `Compat::Pages#get(id, stage_id:)` currently ignores `stage_id` — this is a GAP.
-  A future improvement: if `stage_id` is provided, filter the returned page to show only
-  that stage's fields. But the mutation must still include `stageId`.
-
-### Stage permissions
-
-**APIv2:** Per-stage permissions enforced at fetch time — requesting a forbidden stage
-returns no data or an error.
-
-**GraphQL:** Stage data is included or excluded silently based on permissions — no
-access errors, just reduced data. A stage the user can't access simply won't appear in
-`stages` or `stagesIndex`. (Needs double-check with Engineering.)
-
-**Implication:** Scripts that rely on access errors from APIv2 to detect permission
-boundaries may not get the same signal from GraphQL. Scripts should check whether the
-stage they expect is present in the response.
-
-### `as_update` usage in eco-helpers
-
-`as_update` is called in eco-helpers for two purposes:
-1. **Simulate/dry_run mode:** Print what would change without sending the request.
-2. **Dirty detection:** `dirty?(page)` = `!page.as_update.nil?` (v2 pattern).
-
-Our compat `dirty?` already delegates to `as_update` via `PageCompat`. ✓
-
-For simulate mode: when `graphql.pages.update(page)` is called in dry_run mode,
-eco-helpers should call `pages.get_body(page)` (= `page.as_update`) and display the
-diff without making the HTTP request.
-
-### `add_component` / `add_field` gap
-
-APIv2 allows adding NEW fields to a page via `components.add(...)`. In GraphQL,
-`updatePage` has `dataFields: { additions: [DataFieldInput], updates: [...], deletions: [ID] }`.
-We implemented `updates` only. `additions` is not yet supported in the compat layer.
-
-**Consequence:** Scripts that call `add_field` or `components.add` will not work yet.
-This is a known gap. Document it for the integration test phase.
-
-### `apiv2.pages.create|update` redirect
-
-The eco-helpers `Eco::API::Session` manages an `apiv2` object. Redirecting to GraphQL
-requires swapping the `apiv2` session backend without changing scripts. Two approaches:
-
-1. **Session-level swap (eco-helpers):** Override `apiv2.pages` and `apiv2.registers`
-   in the eco-helpers session to return the GraphQL compat objects. Scripts are unchanged.
-   This is the cleanest approach for the 3-week deadline.
-
-2. **Proxy class:** Create `Ecoportal::API::GraphQL::V2Proxy` that mimics the full V2
-   API surface. Assign this as the session backend when GraphQL mode is active.
-
-The GraphQL gem already provides `graphql.pages` and `graphql.registers`. The eco-helpers
-change is only in how the session wires the backend — NOT in the scripts themselves.
-
-### Template updates
-
-Engineering does NOT want template updates via GraphQL currently — templates are still
-managed via the old AngularJS front-end. Do NOT expose template mutation endpoints from
-the compat layer. `Query::Templates` (read-only list) is fine. Mutations against templates
-should be blocked or at minimum undocumented.
-
-### Forces (AngularJS front-end snippets)
-
-Forces are embedded front-end code snippets that attach to specific stages based on
-their bindings. They are being REPLACED by the Workflow Builder (see below). Low priority
-for scripting integration. Forces are not queryable/mutable via GraphQL in a meaningful way.
-
-### Workflow Builder (in progress, high change velocity)
-
-The Workflow Builder (`pagesWorkflow`) allows configuring automated behaviours:
-- Deployed: notifications, auto page creation, task assignments
-- Not yet deployed: conditional field/section workflows (show/hide sections based on
-  field values, computed risk ratings, gauge/select interdependencies)
-- Recently refactored (quick fixes via CI/CD for new customers)
-
-**Implication for scripting:** Workflow Builder operations are not part of the
-eco-helpers compat scope. However, scripts must be aware that workflow triggers
-(task creation, stage transitions) can fire as side effects of `updatePage`.
-
-### DSL location decision (confirmed 2026-06-07)
-
-The compat DSL (page accessors, `components`, `stages[name]`, `consolidate!`, etc.)
-sits in `ecoportal-api-graphql` as concerns included on page models. This is correct
-because these are upstream-dependency concerns of this gem.
-
-The eco-helpers `OozeBase` / `RegisterUpdate` inheritance chain will transparently
-use the GraphQL-backed models once the session backend is swapped. No script code changes.
-
-However: some DSL methods (`add_field`, `add_component`, stage-specific submit) may
-need to live in eco-helpers itself if they cannot be cleanly expressed at the gem level.
-
----
-
-## Open Questions (Resolved 2026-06-07)
-
-1. ✓ Filter format: translated in `Compat::Registers` (date_filter lbound/ubound → gte/lte)
-2. ✓ Components naming: `components` aliased to `field_collection` via `DataFieldAccess`
-3. ✓ `get_new` shape: `buildFromTemplate` returns full page with field IDs via `CommonPageUnion`
-4. ✓ Stage access: `StageCollection` wrapper provides `[]`, `get_by_name`, `ordered`
-5. Script repo access: pending `.claude/settings.json` rules configuration
-
-## Remaining Gaps
-
-- `stage_id` in `pages.get` currently ignored — stage-specific view not filtered client-side
-- `stageId` in `updatePage` not yet passed through compat — needed for stage submit/close-out
-- `add_field` / `add_component` (dataFields.additions) not implemented
-- Stage-specific permissions may behave differently (silent omission vs error)

data/.ai-assistance/projects/eco-helpers-compat/MIGRATION_GUIDE.md

@@ -1,266 +0,0 @@
-# eco-helpers → GraphQL Migration Guide
-
-*Migrating eco-helpers scripts from `ecoportal-api-v2` to `ecoportal-api-graphql`.*
-
----
-
-## TL;DR
-
-For most page scripts: **change one line** (the API initialiser). Everything else stays the same.
-
-```ruby
-# Before (APIv2)
-api = Ecoportal::API::V2.new(email: ENV['EMAIL'], pass: ENV['PASS'], org_id: ENV['ORG'])
-
-# After (GraphQL)
-api = Ecoportal::API::GraphQL.new(email: ENV['EMAIL'], pass: ENV['PASS'], org_id: ENV['ORG'])
-```
-
-`api.pages` and `api.registers` expose the same interface — the same method names,
-the same argument shapes, the same block and return-value patterns.
-
----
-
-## What Changes
-
-### Initialiser
-
-| | APIv2 | GraphQL |
-|---|---|---|
-| Class | `Ecoportal::API::V2` | `Ecoportal::API::GraphQL` |
-| Gem | `ecoportal-api-v2` | `ecoportal-api-graphql` |
-| `email:` | ✓ | ✓ |
-| `pass:` | ✓ | ✓ |
-| `org_id:` | ✓ | ✓ |
-| `host:` | ✓ (default `live.ecoportal.com`) | ✓ (same default) |
-
-### Gem dependency in your script's Gemfile
-
-```ruby
-# Remove:
-gem 'ecoportal-api-v2'
-
-# Add:
-gem 'ecoportal-api-graphql'
-```
-
----
-
-## What Stays the Same
-
-### `pages` interface
-
-| Method | APIv2 signature | GraphQL compat | Notes |
-|---|---|---|---|
-| `get(id)` | `pages.get(id)` | ✓ identical | |
-| `get(id, stage_id:)` | `pages.get(id, stage_id: sid)` | ✓ identical | Returns `StageView` |
-| `get_new(template_id)` | `pages.get_new(tid)` | ✓ identical | Returns built PageUnion |
-| `create(page, from:)` | `pages.create(page, from: tid)` | ✓ identical | Returns `PageReference` |
-| `update(page)` | `pages.update(page)` | ✓ identical | Returns `Response` |
-| `get_body(page)` | `pages.get_body(page)` | ✓ identical | Returns change hash |
-
-### Page model accessors
-
-| Accessor | Works? | Notes |
-|---|---|---|
-| `page.id` | ✓ | |
-| `page.name` | ✓ | |
-| `page.external_id` | ✓ | maps to `externalId` |
-| `page.template_id` | ✓ | maps to `sourceTemplateId` |
-| `page.stages?` | ✓ | |
-| `page.stages['Stage Name']` | ✓ | via `Compat::StageCollection` |
-| `page.stages.get_by_name(n)` | ✓ | |
-| `page.stages.ordered.map(&:id)` | ✓ | |
-| `page.current_stage_id` | ✓ | on PhasedPage only |
-| `page.components` | ✓ | returns `DataField::Collection` |
-| `page.components.get_by_name(l)` | ✓ | case-insensitive |
-| `page.components.get_by_type(t)` | ✓ | symbol or string |
-| `page.dirty?` | ✓ | |
-| `page.consolidate!` | ✓ | resets change tracking |
-| `page.validate` | ✓ (always nil) | server validates on mutation |
-| `stage.components` | ✓ | |
-| `stage.sections` | ✓ | |
-| `stage.active?` / `stage.started?` | ✓ | |
-
-### Page reference (after create)
-
-```ruby
-ref = api.pages.create(draft, from: template_id)
-ref.page_id         # ✓
-ref.active_stage_id # ✓
-ref.success?        # ✓
-```
-
-### `registers` interface
-
-| Method | APIv2 | GraphQL compat | Notes |
-|---|---|---|---|
-| `search(id, opts) { \|r\| }` | ✓ | ✓ | Cursor-paginated |
-| `result.id` in block | ✓ | ✓ | |
-| No-block → `.total` | ✓ | ✓ | via `SearchResults` |
-| `.total_before_filtering` | ✓ | ✓ | |
-
----
-
-## What Requires Review
-
-### 1. Filter format in `registers.search`
-
-Scripts that pass v2-style filter hashes are **automatically translated** by
-`Compat::FilterTranslator`. You only need to review if your script passes filters
-in a non-standard or custom format.
-
-**Automatic translation (no action needed):**
-
-```ruby
-# v2 date_filter with lbound/ubound — automatically converted to gte/lte
-{ 'type' => 'date_filter', 'key' => 'updated_at', 'lbound' => '2025-01-01', 'ubound' => '2025-12-31' }
-# → { operation: 'date_filter', params: { key: 'updated_at', gte: '2025-01-01', lte: '2025-12-31' } }
-
-# tag_filter — passed through unchanged (same ES backend)
-{ 'type' => 'tag_filter', 'tags' => [...] }
-
-# register_filter — passed through unchanged
-{ 'type' => 'register_filter', 'params' => { 'ids' => [...] } }
-```
-
-**Requires review:** if your script builds filters with keys like `extact_filter`
-(typo), non-standard operation names, or custom filter shapes not listed above —
-those will pass through unchanged and may return empty results silently.
-See `search_filters.md` for the full list of valid operation names (all snake_case).
-
-**Quick search to run on your script repo:**
-
-```bash
-grep -rn "date_filter\|tag_filter\|filters.*type\|type.*filter" scripts/
-```
-
-### 2. `pages.update` — always fetch before update
-
-The GraphQL path requires `patchVer` for concurrency control.
-`Input::Page::Update.from_model` injects it automatically **if you fetched the page first**.
-
-```ruby
-# Correct — always fetch first
-page = api.pages.get(page_id)
-page.name = 'New Name'
-api.pages.update(page)
-
-# Incorrect — updating a page you constructed manually (no patchVer)
-page = MyManualPageObject.new(...)
-api.pages.update(page)  # ⚠ patchVer will be nil — server may reject
-```
-
-If your script fetches pages via `get` before updating, no change needed.
-If your script constructs page objects manually without fetching — review those paths.
-
-### 3. `get_new` — template ID must be the live template ID
-
-`pages.get_new(template_id)` calls `buildPageFromTemplate` on the GraphQL API.
-The `template_id` must be the live MongoDB ObjectId, same as in APIv2.
-
-The return value has the same structure as in APIv2 — `page.components`,
-`page.stages`, etc. Field IDs are server-assigned instance IDs, not template IDs.
-You must use these IDs when creating the page (the compat layer handles this
-automatically via `page.data_fields_updates`).
-
----
-
-## Known Limitations
-
-### 1. Field types — read access only for some types
-
-The following field types are **readable** but cannot be written via `as_input`:
-
-| Type | Status | Notes |
-|---|---|---|
-| `Signature` | Read only | Captured via UI |
-| `Mailbox` | Read only | System-managed |
-| `ActionsList` | Read only | Manage via `api.action` builder |
-| `Law` | Read only | Legal snippets, not editable via script |
-| `AiSummary` | Read only | AI-generated |
-| `Table` | Read only | Complex structure |
-
-The following types **are writable** but require a file upload step first:
-
-| Type | Status | Notes |
-|---|---|---|
-| `File` | Writable* | Requires REST upload → fileContainerIds |
-| `ImageGallery` | Writable* | Same as File |
-
-\* File upload support is on the roadmap. For now, `file_container_ids=` will work
-if you already have `fileContainerIds` from a prior upload.
-
-### 2. `pages.search` — not implemented on `Compat::Pages`
-
-APIv2's `pages.search(...)` is not part of the compat layer.
-Use `api.registers.search(register_id, ...)` for register-scoped search,
-or use `Model::Organization.pages(searchConf: conf)` for org-wide search.
-
-### 3. Performance — org search is ~3s/page
-
-The GraphQL `pages.get` (and `pages.get_new`) fetches full DB-rendered page data.
-This is ~3s per page for large pages, compared to ~200ms in APIv2 for the same data.
-
-Mitigation: batch fetches, or use `api.registers.search` (ES-backed, fast) to
-get page IDs first, then fetch only the pages you actually need to update.
-
-### 4. `simulate?` / dry-run mode — no change
-
-The compat layer honours `get_body` / `dirty?` / `consolidate!` as before.
-Dry-run logic that checks `dirty?` and skips `update` if not dirty continues to work.
-
----
-
-## Quick Verification Checklist
-
-Before switching a script to the GraphQL gem:
-
-- [ ] Grep for `API::V2.new` — replace with `API::GraphQL.new`
-- [ ] Grep for custom filter formats — verify they translate correctly
-- [ ] Grep for manual page construction (without `pages.get`) — check patchVer supply
-- [ ] Grep for `pages.search` — replace with `registers.search` or org search
-- [ ] Run the script in `simulate` mode against a staging org
-
----
-
-## Example: minimal diff for a typical update script
-
-```ruby
-# Before
-require 'ecoportal/api-v2'
-api = Ecoportal::API::V2.new(email: ENV['EMAIL'], pass: ENV['PASS'], org_id: ENV['ORG'])
-
-api.registers.search('REG_ID', filters: [date_range_filter('updated_at', from: '2025-01-01')]) do |result|
-  page = api.pages.get(result.id)
-  next unless page.dirty?
-  page.components.get_by_name('Status')&.select_option('Active')
-  api.pages.update(page)
-  page.consolidate!
-end
-
-# After (change highlighted)
-require 'ecoportal/api-graphql'                                               # ← changed gem
-api = Ecoportal::API::GraphQL.new(email: ENV['EMAIL'], pass: ENV['PASS'], org_id: ENV['ORG'])  # ← changed class
-
-api.registers.search('REG_ID', filters: [date_range_filter('updated_at', from: '2025-01-01')]) do |result|
-  page = api.pages.get(result.id)
-  next unless page.dirty?
-  page.components.get_by_name('Status')&.select_option('Active')
-  api.pages.update(page)
-  page.consolidate!
-end
-# Everything else is identical.
-```
-
----
-
-## Rollback
-
-If a script needs to revert to APIv2:
-
-1. Change the require back to `ecoportal/api-v2`
-2. Change the initialiser class back to `Ecoportal::API::V2`
-3. No other code changes needed
-
-The compat layer was designed so the rollback is always a one-line change.

data/.ai-assistance/projects/eco-helpers-compat/TODO.md

@@ -1,86 +0,0 @@
-# TODOs — eco-helpers GraphQL Compat Layer
-
-> URGENT — APIv2 retires in ~3 weeks.
-> Natural order: 1 → 2 → 3 → 4 → 5 (resolve open questions before implementing)
-
----
-
-## Step 1 — Resolve open questions (Done 2026-06-07)
-
-- [x] **1.1** Filter format confirmed: scripts use `tags_filter` and `date_range_filter`
-  helpers producing `type: "date_filter"` with `lbound`/`ubound` keys.
-  Translation: date_filter lbound→gte, ubound→lte. Other types pass through.
-
-- [x] **1.2** `registers.search` block result: yields individual PreviewPage objects (.id etc).
-  No-block form returns an object with `.total` and `.total_before_filtering`.
-  Implemented: `Compat::SearchResults` wraps connection with both properties.
-
-- [ ] **1.3** `pages.get_new` draft shape — still waiting on end-script repo access.
-  For now: `buildPageFromTemplate` returns PageUnion with field IDs and stagesIndex.
-
-- [x] **1.4** `pages.create` reference: only `.page_id` and `.active_stage_id` used.
-  `Compat::PageReference` implements both correctly.
-
-- [x] **1.5** Stage access: `stages[id_name]` AND `stages.get_by_name(id_name)` AND
-  `stages.ordered.map(&:id)`. Implemented via `Compat::StageCollection` wrapper
-  included via `Model::Page::Phased#stages` override.
-
----
-
-## Step 2 — Scaffold `Compat::Pages` and `Compat::Registers` (Done 2026-06-07)
-
-- [x] **2.1** `lib/ecoportal/api/graphql/compat/pages.rb`: `get`, `get_new`, `create`, `update`, `get_body`.
-  *Done 2026-06-07*
-
-- [x] **2.2** `lib/ecoportal/api/graphql/compat/registers.rb`: `search` with cursor pagination
-  and v2 filter translation (date_filter lbound/ubound → gte/lte).
-  *Done 2026-06-07*
-
-- [x] **2.3** Wired from top-level `Ecoportal::API::GraphQL`: `pages` → `Compat::Pages`, `registers` → `Compat::Registers`.
-  *Done 2026-06-07*
-
----
-
-## Step 3 — Page model compatibility wrapper (Done 2026-06-07)
-
-- [x] **3.1** `Concerns::PageCompat` included in `Interface::BasePage`:
-  `external_id`, `template_id`, `components`, `stages?`, `consolidate!`, `validate`, `dirty?`.
-  `current_stage_id` defined on `Model::Page::Phased` (reads in-progress stage from doc).
-  19 specs: `spec/ecoportal/api/graphql/concerns/page_compat_spec.rb`.
-  *Done 2026-06-07*
-
-- [x] **3.2** `Compat::StageCollection`: `stages[id_or_name]`, `get_by_name`, `ordered`.
-  Wrapped via `Model::Page::Phased#stages` override.
-  Specs: `spec/ecoportal/api/graphql/compat/stage_collection_spec.rb`.
-  *Done 2026-06-07*
-
-- [x] **3.3** `Compat::PageReference`: `.page_id` and `.active_stage_id` (via `current_stage_id`).
-  Fixed: was using `currentStage` (undefined accessor); now uses `current_stage_id`.
-  Specs: `spec/ecoportal/api/graphql/compat/page_reference_spec.rb`.
-  *Done 2026-06-07*
-
----
-
-## Step 4 — Search/filter translation
-
-- [x] **4.1** `Compat::FilterTranslator.to_graphql(v2_filter)` — translates v2 filter hashes
-  to `SearchConf` objects. Handles `date_filter` (lbound→gte, ubound→lte), `tag_filter`,
-  `exact_filter`, `register_filter`; extracted from `Compat::Registers`.
-  *Done 2026-06-07 — 12 specs in `spec/ecoportal/api/graphql/compat/filter_translator_spec.rb`*
-
-- [x] **4.2** `Logic::BaseQuery#normalize_variables` auto-calls `.to_h` on value objects
-  (e.g. `SearchConf`) before passing as GraphQL variables — callers no longer need explicit `.to_h`.
-  *Done 2026-06-07 (commit cc72902)*
-
----
-
-## Step 5 — Integration test + migration guide
-
-- [ ] **5.1** Run a real end-script against the compat layer (requires end-script repo access).
-  User will provide once `.claude/settings.json` rules are set.
-
-- [x] **5.2** `.ai-assistance/projects/eco-helpers-compat/MIGRATION_GUIDE.md` written.
-  Covers: one-line initialiser change, API compatibility table, filter review checklist,
-  patchVer requirement, known limitations (read-only field types, no pages.search,
-  ~3s/page performance), example diff, rollback instructions.
-  *Done 2026-06-08*

data/.ai-assistance/projects/ecoportal-api-v2-doublemodel-review/INTENT.md

@@ -1,101 +0,0 @@
-# Project: DoubleModel Review & Stabilisation (`ecoportal-api-v2`)
-
-**Created:** 2026-06-05
-**Status:** idea — not started
-**Primary repo:** `ecoportal-api-v2`
-**Affects:** `ecoportal-api-graphql` (consumers of `as_update` / `as_input` cascade)
-**Blocks:** `dynamic-model-generation` project
-
----
-
-## Goal
-
-Review and stabilise the `DoubleModel` implementation in `ecoportal-api-v2`, with particular
-focus on:
-
-1. The `doc` / `original_doc` lookup chain through nested and Array-indexed models.
-2. The `root!` / `read_only!` memoisation flags and their interaction with the cascaded diff.
-3. Ensuring that memoised `@doc` cannot silently go out of sync with a parent's diff.
-
-The outcome must be a `DoubleModel` contract that is reliable enough to underpin
-`ecoportal-api-graphql`'s `as_update` / `as_input` pipeline and, eventually, auto-generated
-model classes.
-
----
-
-## Background
-
-The `DoubleModel` stores the canonical document (`@doc`) only at the root object. All
-nested descendant objects resolve their own `doc` by walking up the ownership chain and
-extracting their slice of the root `@doc` by key path.
-
-This design is correct for Hash-keyed paths (keys are deterministic). It breaks down for
-Array-indexed paths (`CollectionModel` and similar), because Array indexes are positional —
-if order changes, a nested object's key path no longer resolves to the right element.
-
-The current workaround is to look up the element by its own key from the parent at access
-time, rather than by stored index. This lookup is performed every time `doc` or
-`original_doc` is called on a nested object inside an Array, making it operationally costly:
-
-- The lookup re-scans the parent array on each call.
-- Objects under a `CollectionModel` may be instantiated multiple times during a single render
-  as a side effect of these repeated resolutions.
-
-To mitigate this, `root!` and `read_only!` class-level flags were introduced. They allow
-a model class to memoise `@doc` locally (breaking the chain) when it is known to be stable.
-These flags are used extensively in `ecoportal-api-graphql` model and payload classes.
-
-### Known risk
-
-`root!` also signals to the cascaded diff (`DiffService`) that the object should be
-excluded from the parent's diff. This is correct for read-only lookup objects (e.g. a
-referenced Location node). But if `root!` is applied at a level where the object *is*
-expected to contribute changes to the parent diff, the memoised `@doc` will silently
-go out of sync — changes to that sub-model will not surface in `as_update`. This is
-a subtle correctness risk that needs to be audited across all uses of `root!` and
-`read_only!` in `ecoportal-api-graphql`.
-
----
-
-## Scope
-
-- Audit all uses of `root!` and `read_only!` in `ecoportal-api-graphql` model and payload
-  classes: confirm each is correctly applied (genuinely read-only / excluded from diff).
-- Review the Array-indexed lookup in `CollectionModel` (and related): document the current
-  behaviour, identify cases where it causes multiple object instantiation.
-- Propose and implement a more efficient resolution strategy for Array-indexed nested models
-  that does not require rescanning on every `doc` / `original_doc` call.
-- Ensure `patch_ver` propagation through the chain is correct after any changes.
-- Confirm that the `initial_doc` / `original_doc` / `doc` three-state contract is
-  preserved correctly after any refactor.
-
----
-
-## Spec-first requirement
-
-Specs related to any modification **must be written before the change is applied** to
-`ecoportal-api-v2`, to lock in current behaviour and guard backwards compatibility.
-Specs must also be maintained and extended after the change to prevent future regressions.
-
-This applies both to the `ecoportal-api-v2` spec suite and to any `ecoportal-api-graphql`
-specs that exercise the cascaded diff path.
-
----
-
-## Open Questions
-
-- Is the Array-indexed lookup fixable with a simple cache keyed by object identity
-  (`object_id`) that is invalidated on `doc=` / `reset!` calls?
-- Are there cases in `ecoportal-api-graphql` where `root!` is applied incorrectly
-  (object should contribute to diff but doesn't)?
-- What is the right `read_only!` vs `root!` semantic split? (`read_only!` = never
-  accept changes; `root!` = store doc locally + exclude from parent diff — are these
-  always the same thing, or should they be separable?)
-
----
-
-## Notes
-
-This project is primarily work in `ecoportal-api-v2`, but the review must happen with
-`ecoportal-api-graphql` open alongside it, since the usage patterns there drive what
-needs to be fixed.