ecoportal-api-graphql 1.3.11 → 1.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78e2adbcdb62b6d2fdbf2ddb5906d9d8b5b93464af6269936b7eeda2dc94cb17
-  data.tar.gz: e6c55777dab78795abe7b81f419275cb52ec82a986aa92ee0da4affa4d5ca7e8
+  metadata.gz: fba9a366d06303f179c6b7d841930a66a29b6cc3fe836e06b218b95873bbe77e
+  data.tar.gz: 6114ba779317ec55b649e1f7df685c0140573cea073aa07c04b9e4cfa20b433a
 SHA512:
-  metadata.gz: 2bff88bcf06b31025a011fdb2b7d5f4a209aaa92b21c4c6c09ef1439da39a0b1e76fe75a204e5d4bc3e55dda5b7d4d6b215554650007b6d5097afa388ca08537
-  data.tar.gz: 0df6a4578b1ddbefa765f813fd97efd5f8e55fc84ad0384a7e7e6459f2ddc040dc6d8999af2493bb4e6368a638254ca7d8ed2154b7eae27bc40b965b80a94be4
+  metadata.gz: d867c896796e9107870a2a49e3cdc75275b0a96559a9b8fe47fedea407ef639f7ff558ce22de798f79f3f011c7d4464a3eacd01a63e764778d2e0359cd8ed4ad
+  data.tar.gz: c29f555f19fc3d679f51cb512c417caca1e7e5f0006e9ac35a7ccf4d7f074095011ad4a59128a458b69c178dd538d79bf952d1b26b1557397e0d5fc4c41274d4

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

@@ -0,0 +1,177 @@
+# Filter Contract Matrix — GraphQL register/page filters
+
+**Purpose.** Evidence-based ground-truth mapping of *ES register/page filter operations* to
+their exact params, per register field type, so the compat `FilterTranslator` can be validated
+against the backend rather than conjecture. Built after the Date/Select translator bug
+(commit e45ba58) where the original translation table was never validated.
+
+**Authoritative source.** `ecoPortal_master` Rails backend, `NewEp::Es` filter stack:
+
+- **Field-type → allowed operations** (the contract a register exposes):
+  `app/services/new_ep/es/definitions/page.rb`
+- **Operation → exact params** (constructor kwargs / `argument` declarations):
+  `app/services/new_ep/es/filters/pages/**` and `.../filters/global/**`
+- **Operation string → class dispatch:**
+  `app/services/new_ep/es/filters/deserializer.rb:51-58` — the `operation` string is
+  `camelize`d + suffixed `Filter`, resolved **first** under `NewEp::Es::Filters::Pages::`,
+  then falling back to `NewEp::Es::Filters::Global::`. An operation with no matching class
+  raises `UnknownFilterError` (`deserializer.rb:59`). This is why `options_filter` /
+  `text_filter` (v2 names) are NOT valid GraphQL operations — see §"v2 → GraphQL" below.
+
+All line numbers below are `file:line` in `ecoPortal_master` unless noted. GraphQL param names
+match the backend constructor / `argument` declarations exactly.
+
+---
+
+## 1. v2 → GraphQL translator input types (what `Compat::FilterTranslator` handles)
+
+`lib/ecoportal/api/graphql/compat/filter_translator.rb` accepts *v2-style* `type:` hashes and
+emits GraphQL `{operation:, params:}` hashes. The v2 `type` names are NOT backend operation
+names; the emitted `operation` names ARE. Every emitted operation below resolves to a real
+backend class (verified via the deserializer dispatch).
+
+| v2 `type` | Emitted GraphQL `operation` | Emitted params | Backend class (evidence) | Translator handles? |
+|---|---|---|---|---|
+| `date_filter` (system key, e.g. `created_at`) | `date_filter` | `key, time_zone, gte?(=lbound), lte?(=ubound)` | `Global::DateFilter` — `date_filter.rb:28` (`key, path, gt, gte, lt, lte`) | YES (`filter_translator.rb:110-124`) |
+| `date_filter` (field key, e.g. `date.zXXXX`) | `range_date_filter` | `key, path=membranes.date, time_zone, gte?, lte?` | `Pages::RangeDateFilter` — `range_date_filter.rb:797` (`key, path, gte, lte, gt, lt`) | YES (`filter_translator.rb:110-124`) |
+| `text_filter` | `match_filter` | `key, value(=query)` | `Global::MatchFilter` — `match_filter.rb:6` (`key, value, path`) | YES (`filter_translator.rb:74-82`) |
+| `exact_filter` / `is_filter` | `is_filter` | `key, path?(derived membranes.<type>), value` | `Pages::IsFilter` — `is_filter.rb:258` (`key, path, value`) | YES (`filter_translator.rb:52-57`) |
+| `options_filter` (system key) | `one_of_filter` / `none_of_filter` (exclude) | `key, values(=chosen)` | `Global::OneOfFilter` — `one_of_filter.rb:16` (`key, values`); `Global::NoneOfFilter` — `none_of_filter.rb:6` (`key, values`) | YES (`filter_translator.rb:90-104`) |
+| `options_filter` (field key, e.g. `select_str.zXXXX`) | `has_any_filter` / `doesnt_have_any_filter` (exclude) | `key, path(=membranes.<type>), field_key='selected', values(=chosen)` | `Pages::HasAnyFilter` — `has_any_filter.rb:995` → `Pages::BaseHasAnyFilter` — `base_has_any_filter.rb:10` (`key, path, field_key, values, invert`); `Pages::DoesntHaveAnyFilter` — `doesnt_have_any_filter.rb:1061` | YES (`filter_translator.rb:90-104`) |
+| `tag_filter` | *(passthrough — no rewrite)* | — | n/a (already GraphQL-shaped) | passthrough (`filter_translator.rb:37-39`) |
+| `register_filter` | *(passthrough)* | — | `Pages::RegisterFilter` (`filters/pages/register_filter.rb`) | passthrough |
+| `and_filter` / `or_filter` | *(passthrough)* | — | `Global::AndFilter` / `Global::OrFilter` | passthrough |
+| already-`{operation:,params:}` hash | *(passthrough)* | — | — | passthrough (unmatched `type`) |
+| SearchConf value object (`to_h`, not Hash) | *(passthrough)* | — | — | passthrough (`filter_translator.rb:25`) |
+
+### Why `options_filter` / `text_filter` are NOT emitted verbatim
+
+- **`options_filter`**: there is NO `Pages::OptionsFilter` or `Global::OptionsFilter` class.
+  The closest backend class is `Pages::OptionsFieldFilter` (op `options_field_filter`,
+  `options_field_filter.rb:9`, takes `chosen`/`mode`) — a *different* operation the register
+  definitions never expose. Emitting `options_filter` verbatim would raise `UnknownFilterError`.
+  So the translator rewrites to the backend-blessed `has_any_filter`/`one_of_filter`.
+- **`text_filter`**: a `Pages::TextFilter` class DOES exist (`text_filter.rb:1252`) but its
+  constructor takes `key:, query:` (not `value:`) and register definitions never expose a
+  `text_filter` operation — they expose `contains_filter`/`is_filter`. The translator therefore
+  emits `match_filter` (`Global::MatchFilter`, `match_filter.rb:6`), which is a valid operation
+  with `{key, value}`. NOTE: `match_filter` matches the *analyzed* value (partial/full-text);
+  for whole-value exact use `is_filter` (see §exact-vs-partial in `search_filters.md`).
+
+---
+
+## 2. Field-type contract matrix (register/page fields)
+
+One row per **(field type, operation)** enumerated from `page.rb`. `key` = field definition key
+(`<type>.zXXXX`); `path` = the nested membranes path the definition hardcodes. `field_key` /
+`values` shown where the operation carries a subfield. "Translator?" marks whether the compat
+`FilterTranslator` currently produces this operation from a v2 input.
+
+### 2.1 System / metadata fields (no `membranes.*` path)
+
+| Field | v2 type | GraphQL operation(s) | params | page.rb evidence | Translator? |
+|---|---|---|---|---|---|
+| Created on / Updated on | `date_filter` | `date_filter`, `isnt_in_date_filter` | `key=created_at`, gte/lte/time_zone | `page.rb:31-39` | YES (system date branch) |
+| External ID | `exact_filter` | `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter` | `key=external_id`, value | `page.rb:65-70` | YES via `exact_filter`→`is_filter` (no path — system key) |
+| Page ID (`mould_counter`) | — | `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter`, `contains_filter`, `doesnt_contain_filter` | `key=mould_counter`, value | `page.rb:72-79` | is_filter YES; contains_filter NO |
+| Page name (`name`) | `text_filter`/`exact_filter` | `is_filter`, `isnt_filter`, `contains_filter`, `doesnt_contain_filter` | `key=name`, value | `page.rb:81-86` | is_filter YES; match/contains partial: `text_filter`→`match_filter` (valid but `name` uses QueryFilter internally — see NOTE) |
+| Page status (`state`) | `options_filter`/`exact` | `is_filter`, `isnt_filter` | `key=state`, value(`@extras`) | `page.rb:87-99` | via `exact_filter`→`is_filter` YES |
+| System ID (`id`) | `exact_filter` | `is_filter`, `isnt_filter`, `one_of_filter` | `key=id`, value / values | `page.rb:101-105` | is_filter + one_of_filter YES |
+| Assigned to | — | `is_filter`, `isnt_filter`, `has_all/any_filter`, `doesnt_have_all/any_filter` | `key=assigned_to`, field_key=`assigned_to`, values | `page.rb:15-22` | NO (no v2 driver) |
+| Created by | — | `is_filter`, `isnt_filter`, `has_any_filter`, `doesnt_have_any_filter` | `key=creator_id`, field_key=`creator_id` | `page.rb:24-29` | NO |
+| Created via (`source`) | — | `is_filter`, `isnt_filter` | `key=source`, value | `page.rb:41-45` | via is_filter YES (if driven) |
+| Custom tags (`other_tags`) | `tag_filter` | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter` | `key=other_tags`, field_key=`other_tags`, values | `page.rb:56-63` | passthrough (`tag_filter`) |
+| Tags / locations (`all_location_ids`) | `tag_filter` | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter` | `key=all_location_ids`, field_key=`all_location_ids`, values | `page.rb:107-114` | passthrough (values lowercased backend-side: `has_any_filter.rb:1024`) |
+| Current Stage (`active_stage_names`) | — | `has_any/all_filter`, `doesnt_have_any/all_filter` | `key=active_stage_names`, field_key=`active_stage_names`, values | `page.rb:138-143` | NO |
+
+NOTE (`name`): `contains_filter` on `name` routes to `Global::MatchFilter` (`contains_filter.rb:453-455`)
+and `is_filter` on `name` routes to `Global::ExactFilter` on `name.exact` (`is_filter.rb:283-284`).
+The translator's `text_filter`→`match_filter{key:'name',value:}` therefore hits the right backend
+class for partial name search.
+
+### 2.2 Register data fields (nested `membranes.<type>` path)
+
+| Field type | GraphQL operation(s) | params (key/path/field_key/values) | page.rb evidence | Backend op class | Translator? |
+|---|---|---|---|---|---|
+| **date** (`date.zXXXX`) | `range_date_filter`, `isnt_in_range_date_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.date`; range: gte/lte/gt/lt/time_zone | `page.rb:191-209` | `Pages::RangeDateFilter` `range_date_filter.rb:797`; field_key resolved to `value` `range_date_filter.rb:822-828` | YES (`date_filter` field branch → `range_date_filter`) |
+| **select_str** (`select_str.zXXXX`) | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.select_str`, field_key=`selected`, values | `page.rb:279-300` | `Pages::HasAnyFilter`→`BaseHasAnyFilter` `base_has_any_filter.rb:10`; search_key=`path.selected` `base_has_any_filter.rb:42-44` | YES (`options_filter` field branch → `has_any_filter`) |
+| **select_num** (`select_num.zXXXX`) | same as select_str, path=`membranes.select_num` | key, path, field_key=`selected`, values | `page.rb:256-277` | `Pages::HasAnyFilter`→`BaseHasAnyFilter` | YES (field branch; caller passes path/`select_num` prefix) |
+| **plain_text** (`plain_text.zXXXX`) | `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter`, `contains_filter`, `doesnt_contain_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.plain_text`; is_filter → `.exact` subfield | `page.rb:145-165` | `is_filter`→`Pages::IsFilter`→`BaseIsFilter` search_key=`exact` `is_filter.rb:315-316`; contains→`Pages::TextFilter` `contains_filter.rb:459-461` | is_filter YES (exact_filter→is_filter); contains NO |
+| **rich_text** (`rich_text.zXXXX`) | `contains_filter`, `doesnt_contain_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.rich_text`; contains → `content` subfield | `page.rb:303-321` | `contains_filter`→`BaseContainsFilter` field_key=`content` `contains_filter.rb:477-478` | NO (no is/exact op; contains only) |
+| **number** (`number.zXXXX`) | `numeric_range_filter`, `isnt_in_numeric_range_filter`, `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.number`; range: gte/lte/gt/lt on `.value` | `page.rb:168-188` | `numeric_range_filter`→`Pages::NumericRangeFilter` search_key=`path.value` `numeric_range_filter.rb:941-943` | is_filter YES; numeric_range NO |
+| **gauge** (`gauge.zXXXX`) | `is_filter`, `isnt_filter`, `numeric_range_filter`, `isnt_in_numeric_range_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.gauge` | `page.rb:234-254` | numeric via `NumericRangeFilter`; is via `IsFilter` search_key=`value` `is_filter.rb:317-318` | is_filter YES; numeric_range NO |
+| **file** (`file.zXXXX`) | `has_any_filter`, `doesnt_have_any_filter` (×`file_container_id`, `content_type`), `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.file`, field_key=`file_container_id`\|`content_type`, values | `page.rb:212-232` | `has_any_filter`→`Pages::File::HasAnyFilter` `has_any_filter.rb:1034-1035` | NO |
+| **image_gallery** (`image_gallery.zXXXX`) | `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.image_gallery` | `page.rb:545-561` | `is_empty`→`Pages::ImageGallery::IsEmptyFilter` `is_empty_filter.rb:572-573` | NO |
+| **people** (`people.zXXXX`) | `has_any/all_filter`, `doesnt_have_any/all_filter` (×`id`/`contractor_organization_id`/`schema_id`/`prefilter_location_ids`), `is_direct_supervisor_filter`, `has_direct_supervisor_filter`, `is/isnt_contractor_administrator_filter`, `people_field_contains_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.people`, field_key varies, values | `page.rb:466-499` | `Pages::People::HasAnyFilter` `has_any_filter.rb:1030-1031` | NO |
+| **contractor_entities** (`contractor_entities.zXXXX`) | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.contractor_entities`, field_key=`contractor_entities_ids`, values | `page.rb:324-344` | `BaseHasAnyFilter`; `required_data` loads ContractorEntity `base_has_any_filter.rb:27-28` | NO |
+| **cross_reference / page_reference** (`cross_reference.zXXXX`, `any_reference_field`) | `has_any_filter`, `doesnt_have_any_filter`, `has_all_filter`, `doesnt_have_all_filter`, `meets_conditions_filter`(if CRR), `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.cross_references`, field_key=`id`, values=`@page_id`; meets_conditions: `register_id` | `page.rb:502-542` | `Pages::CrossReferences::HasAnyFilter` `has_any_filter.rb:1021-1022` | NO |
+| **actions_list** (`actions_list.zXXXX`) | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.actions_list`, field_key=`id`, values=`@action_id` | `page.rb:347-367` | `Pages::ActionsList::HasAnyFilter` `has_any_filter.rb:1032-1033` | NO |
+| **checklist** (`checklist.zXXXX`) | `all_options_ticked_filter`, `not_all_options_ticked_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.checklist` | `page.rb:445-463` | `all_options_ticked_filter` = `Pages::AllOptionsTickedFilter` (`all_options_ticked_filter.rb`) | NO |
+| **geo** (`geo.zXXXX`) | `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.geo`; is → `address.exact` subfield | `page.rb:370-388` | `IsFilter` search_key=`address.exact` `is_filter.rb:319-320` | is_filter YES (if driven); rest NO |
+| **signature** (`signature.zXXXX`) | `is_filter`, `isnt_filter` (value=`@user_id`), `range_date_filter`, `isnt_in_range_date_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.signature`; is → `signed_by_id`; range → `date` subfield | `page.rb:391-411` | `IsFilter` search_key=`signed_by_id` `is_filter.rb:323-324`; range → `Pages::Signature::RangeDateFilter` `range_date_filter.rb:810-811` | is_filter/range partial (translator emits generic ops; subfield resolution is backend-side by key prefix) |
+| **mailbox** (`mailbox.zXXXX`) | `range_date_filter`, `isnt_in_range_date_filter`, `has_any/all_filter`, `doesnt_have_any/all_filter` (×`all_recipients`/`sender_email`), `contains_filter`, `doesnt_contain_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.mailbox`, field_key varies, values | `page.rb:414-442` | `Pages::Mailbox::*` `has_any_filter.rb:1019-1020` | NO |
+| **law** (`law.zXXXX`) | `has_any_filter`, `doesnt_have_any_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.law`, field_key=`snippets_ids`, values=`@law_snippet_id` | `page.rb:564-582` | `BaseHasAnyFilter`; `required_data` loads Snippet `base_has_any_filter.rb:29` | NO |
+
+---
+
+## 3. Operation → param contract (backend constructor signatures)
+
+Cited so the guard spec asserts exact param shapes. All under
+`app/services/new_ep/es/filters/`.
+
+| Operation | Namespace / class | Constructor params (evidence) |
+|---|---|---|
+| `date_filter` | `Global::DateFilter` | `key, path?, gt?, gte?, lt?, lte?` — `global/date_filter.rb:28` |
+| `range_date_filter` | `Pages::RangeDateFilter` | `key, path?, gte?, lte?, gt?, lt?` — `pages/range_date_filter.rb:797` |
+| `is_filter` | `Pages::IsFilter` | `key, path?, value?` — `pages/is_filter.rb:258` |
+| `isnt_filter` | `Pages::IsntFilter` | `key, path?, value` — `pages/isnt_filter.rb:360` |
+| `match_filter` | `Global::MatchFilter` | `key, value, path?` — `global/match_filter.rb:6` |
+| `contains_filter` | `Pages::ContainsFilter` | `key, path?, value` — `pages/contains_filter.rb:445` |
+| `has_any_filter` | `Pages::HasAnyFilter` → `BaseHasAnyFilter` | `key, path?, field_key?, values` — `pages/has_any_filter.rb:995`, `pages/base_has_any_filter.rb:10` |
+| `has_all_filter` | `Pages::HasAllFilter` → `BaseHasAllFilter` | `key, path?, field_key?, values` — `pages/has_all_filter.rb:1135`, `pages/base_has_all_filter.rb:59` |
+| `doesnt_have_any_filter` | `Pages::DoesntHaveAnyFilter` | `key, path?, field_key?, values` (invert) — `pages/doesnt_have_any_filter.rb:1061` |
+| `doesnt_have_all_filter` | `Pages::DoesntHaveAllFilter` | `key, path?, field_key?, values` (invert) — `pages/doesnt_have_all_filter.rb:1199` |
+| `one_of_filter` | `Global::OneOfFilter` | `key, values` — `global/one_of_filter.rb:16` |
+| `none_of_filter` | `Global::NoneOfFilter` | `key, values` — `global/none_of_filter.rb:6` |
+| `numeric_range_filter` | `Pages::NumericRangeFilter` | `key, path?, gte?, lte?, gt?, lt?` — `pages/numeric_range_filter.rb:917` |
+| `is_empty_filter` | `Pages::IsEmptyFilter` | `key, path?` (search_key by type) — `pages/is_empty_filter.rb:552` |
+| `presence_filter` | `Pages::PresenceFilter` | `key, path?` — `pages/presence_filter.rb:724` |
+
+---
+
+## 4. Known-UNCOVERED field types / operations (visible gap, not silent)
+
+The compat `FilterTranslator` intentionally translates only the v2 filter shapes that real
+consumers emit (`date_filter`, `text_filter`, `exact_filter`/`is_filter`, `options_filter`,
+plus passthroughs). The following register field types / operations have a backend contract
+(cataloged above) but NO translator branch. This is by design — do not add speculative
+translations without a consumer. The guard spec enumerates these so the gap stays visible.
+
+**Field types with NO dedicated translator path** (any v2 filter targeting them falls through
+to passthrough — the caller must pass a pre-shaped `{operation:,params:}` hash):
+
+- `number` (numeric_range_filter), `gauge` (numeric_range_filter)
+- `rich_text` (contains_filter / doesnt_contain_filter)
+- `file` (has_any_filter on file_container_id / content_type)
+- `image_gallery` (is_empty / presence only)
+- `people`, `contractor_entities`, `cross_reference` / `page_reference`
+- `actions_list`, `checklist`, `mailbox`, `law`, `signature` (range/is subfields)
+- `geo` (is_filter on address.exact — reachable via exact_filter if the caller sets key `geo.zXXXX`)
+
+**System fields with NO translator driver:** `assigned_to`, `creator_id` (Created by),
+`active_stage_names` (Current Stage), `mould_counter` contains_filter.
+
+**Operations never emitted by the translator** (must be passed pre-shaped): `has_all_filter`,
+`doesnt_have_all_filter`, `numeric_range_filter`, `isnt_in_numeric_range_filter`,
+`isnt_in_range_date_filter`, `contains_filter`, `doesnt_contain_filter`, `is_empty_filter`,
+`isnt_empty_filter`, `presence_filter`, `not_presence_filter`, `meets_conditions_filter`,
+`all_options_ticked_filter`, `people_field_contains_filter`, direct-supervisor / contractor-admin
+filters.
+
+---
+
+## 5. Change log
+
+- 2026-07-08 — Initial matrix built from `page.rb` + `filters/pages/**` + `filters/global/**`.
+  Guard spec `spec/ecoportal/api/graphql/compat/filter_translator_spec.rb` extended to pin every
+  emitted operation to its backend param contract and to enumerate the uncovered types.

data/.ai-assistance/projects/compat-layer-audit/COMPAT_AUDIT.md

@@ -0,0 +1,244 @@
+# GraphQL COMPAT Layer Audit — contract fidelity vs ecoportal-api-v2
+
+> READ-ONLY audit. No code changed, no git touched. Date: 2026-07-08.
+> Scope: every place the GraphQL gem re-expresses a v2 public API, measured against the
+> v2 contract as source of truth. Consumers surveyed: `multi_org_api/*/config/ooze_cases`,
+> eco-helpers `usecases/graphql` + `OozeRedirect` + `ooze_samples`.
+
+---
+
+## 1. Executive verdict — AD-HOC PATCH, not a faithful mirror
+
+Oscar is **right**. The compat layer is a set of reactive, per-symptom patches, not a
+contract-faithful mirror of the v2 API. Concrete evidence:
+
+1. **Same method, three different return-type decisions, no shared contract.** `get_by_name`
+   is a COLLECTION in v2 for components, forces, and bindings, but a SINGLE for stages. The
+   gem got forces (`base/force/collection.rb:16` → `select`), bindings
+   (`base/force/binding_collection.rb:19` → `select`), and stages
+   (`compat/stage_collection.rb:34` → `find`, correct) right — but got **components wrong**
+   (`base/page/data_field/collection.rb:35` → `find`) and **sections' `get_by_heading` wrong**
+   (`base/page/section_collection.rb:31` → `find`, v2 is `select`). Three files, four
+   independent return-type choices. A faithful mirror would have one rule per v2 method; this
+   has ad-hoc choices that happen to match in some files and not others.
+
+2. **The downstream consumer already contains a workaround for the gem's wrong return type.**
+   eco-helpers `OozeRedirect#with_fields` wraps the component lookup:
+   `[collection.get_by_name(label)].compact` (`ooze_redirect.rb:187`) — i.e. it treats
+   `get_by_name` as returning a SINGLE and re-wraps it into an array to fake the v2 collection
+   contract. That is a patch compensating for a patch. When the gem is made faithful (returns a
+   collection), this line double-wraps → `[[Field]]`. Whack-a-mole in the flesh.
+
+3. **Two conflicting `#components` definitions on the same object.** `Concerns::PageCompat#components`
+   returns `dataFields || []` (`page_compat.rb:22`); `Concerns::DataFieldAccess#components`
+   returns `field_collection` (`data_field_access.rb:22`). Both are `include`d in
+   `Interface::BasePage` (`base_page.rb:6-7`), DataFieldAccess second so it wins — but the dead
+   PageCompat version returning a raw array is a fossil of an earlier, incompatible attempt.
+
+4. **Methods the v2 contract guarantees are simply absent** (not deliberately dropped —
+   nobody enumerated the contract): `DataField::Collection` has no `get_by_id`, no
+   `get_by_type` returning a `reference?`-style API, no `unattached`/`multi_section`;
+   `SectionCollection` has no `get_by_id`, no `ordered`-by-weight, no `between`. Consumers call
+   `components.get_by_id` and `sections.get_by_id` today (§3).
+
+5. **`components.add` has different semantics** — v2 `upsert!`s into the live collection so a
+   later `get_by_name` finds it; the gem stashes into a private `@additions` array
+   (`collection.rb:53-60`) that `each`/`get_by_name` never see.
+
+The through-line: each method was added when a specific script broke, choosing whatever return
+shape that one script needed — never derived from the v2 method's documented contract. That is
+the definition of ad-hoc.
+
+---
+
+## 2. Divergence catalog
+
+Severity: **S1** = silent wrong result / breaks live consumers; **S2** = raises / missing method;
+**S3** = latent (no current consumer but contract-divergent).
+
+| # | Method | v2 contract (file:line) | gem compat (file:line) | Divergence | Sev | Affected consumers |
+|---|--------|-------------------------|------------------------|------------|-----|--------------------|
+| C1 | `components.get_by_name(name, type:)` | `select` → **Array** (`v2/page/components.rb:37`) | `find` → **single DataField** (`base/page/data_field/collection.rb:35`) | Return type: collection vs single | **S1** | act-gov `.first`/`.last`, farmers `.first`, and ~120 `components.get_by_name(...).first` call-sites across multi_org_api (twg, tng, briscoes, alexander, argenta, whittlesea…); eco-helpers `ooze_redirect.rb:184,187` |
+| C2 | `sections.get_by_heading(h, mild:)` | `ordered.select` → **Array** (`v2/page/sections.rb:61`) | `find` → **single Section** (`base/page/section_collection.rb:31`) | Return type + drops `mild:` + no weight-ordering | **S1** | `tng_env_update_case.rb:19` (`.get_by_heading("Details").first`) |
+| C3 | `components.get_by_id(id)` | `find` → single (`v2/page/components.rb:21`) | **absent** on `DataField::Collection` | Missing method → `NoMethodError` | **S2** | `event_changes_case.rb:50` (`components.get_by_id(fld.reference_id)`); eco-helpers `ooze_update_case.rb:10` |
+| C4 | `sections.get_by_id(id)` | `find` → single (`v2/page/sections.rb:46`) | **absent** on `SectionCollection` | Missing method → `NoMethodError` | **S2** | `TnG_Active_sitefix_part2_case.rb:106` |
+| C5 | `components.add(...)` | `upsert!` into live collection; found by later `get_by_name`/`each` (`v2/page/components.rb:53`) | stashes in private `@additions`; NOT in `@fields`; later `get_by_name`/`each` miss it (`collection.rb:53-60`) | Mutation semantics diverge | S2 | any multi-step add-then-read script; `add` kwargs also differ (`id:` required, `doc:` shape) |
+| C6 | `sections.get_by_type(t)` | `ordered.select` → Array (`v2/page/sections.rb:53`) | `select` → Array but **not weight-ordered** (`section_collection.rb:25`) | Ordering: v2 orders by weight, gem uses response order | S3 | ordering-sensitive section scripts (latent) |
+| C7 | `components.get_by_type(t)` | `select` → Array, no ordering (`v2/page/components.rb:28`) | `select` → Array (`collection.rb:27`) | **Match** (return type) | ok | argenta `remove_edit_events_case.rb:21,29` (uses `.select` on result — works only because both are Arrays) |
+| C8 | `forces.get_by_name(name)` | `select` → Array (`v2/page/forces.rb:36`) | `select` → Array (`base/force/collection.rb:16`) | **Match** | ok | all `forces.get_by_name(...).first` sites |
+| C9 | `force.bindings.get_by_name(name, type:)` | `select` → Array (`v2/page/force/bindings.rb:102`) | `select` → Array but **drops `type:` kwarg** (`binding_collection.rb:19`) | Partial: arity narrower | S3 | bindings callers pass name only today; `type:` unused |
+| C10 | `stages.get_by_name(name)` | `find` → single (`v2/page/stages.rb:17`) | `find` → single (`compat/stage_collection.rb:34`) | **Match** | ok | eco-helpers `ooze_base_case.rb:109,144`, `register_export_case.rb:137` |
+| C11 | `stages[id_or_name]` | v2 CollectionModel `[]` by key (id) | id **or** name (`stage_collection.rb:27-30`) | Superset (name-fallback) — benign but non-contract | S3 | eco-helpers `stages[id] || stages.get_by_name` (belt-and-braces) |
+| C12 | `forces.get_by_id`, `.ordered`, `.bindings_by_reference` | present (`v2/page/forces.rb:29,64,20`) | **absent** on gem `Force::Collection` | Missing methods | S3 | not called by surveyed consumers (latent) |
+| C13 | `bindings.get_by_id / get_by_type / get_by_reference / reference? / by_name / by_reference` | present (`v2/page/force/bindings.rb:82,92,68,61,26,42`) | **absent** on gem `BindingCollection` | Missing methods | S3 | not called by surveyed consumers (latent) |
+| C14 | `sections.ordered` (by weight) | `sort_by weight` (`v2/page/sections.rb:86`) | returns `@sections` as-is (`section_collection.rb:41`) | Ordering not applied | S3 | latent |
+| C15 | `page.components` (page-level) | v2 components collection | **two conflicting defs**: PageCompat returns `dataFields`/`[]` array (`page_compat.rb:22`), DataFieldAccess returns `Collection` (`data_field_access.rb:22`); include order (`base_page.rb:6-7`) makes DataFieldAccess win, PageCompat one is dead code | Latent footgun / dead code | S2 | any refactor reordering includes silently swaps behaviour |
+| C16 | `entry.components.get_by_name(...).detect{…}` | Array#detect works on v2 collection | gem returns single → `.detect` = `Enumerable#detect` on a **DataField** (iterates its doc?) | Return-type breakage | **S1** | `risks_migration_case.rb:89` (`.get_by_name("Review frequency:").detect{…}`) |
+| C17 | `force.bindings.get_by_name(x).empty?` | Array#empty? | gem Array → ok (C8/C9 correct) | ok | tng `tng_env_update_case.rb:112` |
+
+### Folded-in prior findings (verified against current code)
+
+These are not `get_by_name`-style return-type bugs but are part of the same "compat built ad hoc"
+thread — the read/write CONVERTER contract was never systematically mirrored. Cross-referenced
+against `.ai-assistance/code/model_input_mapping/SYNTHESIS.md` (2026-07-07). **Note:** SYNTHESIS
+marks several as FIXED on `feature/model-input-fixes` (current branch); status below reflects that.
+
+| # | Prior finding | Current status (verified) | File:line |
+|---|---------------|---------------------------|-----------|
+| P1 | `passarray`/`embeds_many` don't diff via `as_update` (otherTags, locations, filterTags) | **FIXED** — `DIFF_CLASS = Diffable::LeafDiffService` now on `Interface::BasePage` | `interface/base_page.rb:13` |
+| P2 | `IdDiff` set-diff machinery non-functional (ContractorEntity/Action) | Reported FIXED via `id_diff_fields` macro (SYNTHESIS §3.2); **not re-verified in this pass** — flagged for confirm | — |
+| P3 | File/Image/Contractor readers use write-key → `[]` | Reported FIXED (SYNTHESIS §3.3); Image fragment `images[].id` was the blocker | `base/page/data_field/{file_field,image_gallery,contractor_entities}.rb` |
+| P4 | DataField read-key ≠ write-key (shape asymmetry) | Partly FIXED (CrossReference was template); File/Image/Contractor per P3 | `.ai-assistance/code/refactoring/datafield-readwrite-shape-asymmetry.md` |
+| P5 | `SnakeCamelAccess` is a one-way method_missing shim, no specs | **STILL TRUE** — `concerns/snake_camel_access.rb`; no spec file exists (`Glob spec/**/snake_camel*` → none). One-way (snake→camel only); silently no-ops single-word methods (`parts.length < 2` → returns as-is) | `concerns/snake_camel_access.rb:50-54` |
+
+---
+
+## 3. Comprehensive fix plan (contract-faithful) + spec risk
+
+The organising principle: **derive each collection method from the v2 method it mirrors, not from
+the one script that broke.** Recommend a small shared helper module so components/sections/forces/
+bindings collections share one contract per method name.
+
+### Fix C1 — `DataField::Collection#get_by_name` → collection (`select`)
+
+Faithful fix: return `pool.select { … }` (mirror `v2/page/components.rb:37`), keeping `type:`.
+
+**Risks these EXISTING gem specs (they assume single return):**
+- `spec/.../base/page/data_field_spec.rb:397-399` — `coll.get_by_name('name').id` → must become `.first.id`
+- `data_field_spec.rb:408` — `coll.get_by_name('Name').value = 'Bob'` → `.first.value =`
+- `data_field_spec.rb:419` — same
+- `data_field_spec.rb:463` — `field = coll.get_by_name('Name')` → `.first`
+- `base/page/phased/stage_spec.rb:72` — `stage.components.get_by_name('Description').value` → `.first.value`
+- `compat/stage_collection_spec.rb:92` — `stage.components.get_by_name('Description').value` → `.first.value`
+- `compat/stage_view_spec.rb:57` — `view.components.get_by_name('Summary').value` → `.first.value`
+- `input/page/update_spec.rb:136` — `page_with_fields.components.get_by_name('Note').value = 'New'` → `.first.value =`
+- `integration/toocs_submit_replay_spec.rb:38` — `page.components.get_by_name('Coding completed by:')` → `.first`
+
+These 9 spec sites LOCK IN the wrong behaviour and must be updated in lockstep with the fix
+(add `.first`). They also confirm the gem's own test suite was written to the ad-hoc behaviour,
+not the v2 contract.
+
+**Also requires a coordinated eco-helpers change:** `ooze_redirect.rb:184-187` — line 187
+`[collection.get_by_name(label)].compact` must become `collection.get_by_name(label)` (already an
+Array), and line 184-185 `field = collection.get_by_name(label); … [field] : []` must select over
+the collection. This is the cross-repo lockstep the audit brief warns about: a "just remove
+`.first`" workaround in org scripts is itself a dirty patch that re-breaks here.
+
+### Fix C2 — `SectionCollection#get_by_heading` → collection (`select`), add `mild:`, order by weight
+
+Faithful: `ordered.select { same_string?(s.heading, h, mild: mild) }`. Add a `same_string?`
+helper (case-insensitive; `mild:` = alnum-only compare per v2). Requires §Fix-C14 (`ordered` by
+weight) for exact parity.
+
+**Spec risk:** no existing gem spec asserts `get_by_heading` (Grep found none) → **no green
+specs go red.** Add new specs (§4). Consumer `tng_env_update_case.rb:19` already does `.first`, so
+it starts working correctly.
+
+### Fix C3 / C4 — add `get_by_id` to `DataField::Collection` and `SectionCollection`
+
+`find { |x| x.id == id }` (mirror v2). **No spec risk** (new methods). Add coverage.
+
+### Fix C5 — `components.add` upserts into the live collection
+
+Faithful: push the built field into `@fields` (or an upsert-by-id) so later `get_by_name`/`each`
+find it, and keep `dirty_additions` sourced from those. **Spec risk:** check `data_field_spec.rb`
+add-section (`:451-465`) — the deletion test reads `get_by_name('Name')` (existing field, fine);
+the add tests assert `dirty_additions` only, so upserting into `@fields` needs a guard that
+`dirty_inputs` (updates) does not double-count additions. Design the split carefully; lock with a
+"add then get_by_name finds it" spec.
+
+### Fix C6 / C14 — order `get_by_type`/`ordered` by weight in `SectionCollection`
+
+Only if sections carry a weight in the GraphQL doc (verify fragment exposes it; if not, response
+order is the only signal and this stays a documented gap). **No current spec risk.**
+
+### Fix C9 / C12 / C13 — fill missing force/binding contract methods + `type:` on bindings
+
+Add `get_by_id`, `get_by_type`, `get_by_reference`, `reference?`, `by_name`, `by_reference`,
+`ordered`, `bindings_by_reference`, and honour `type:` in `binding.get_by_name`. These are S3
+(no live consumer) — do them to make the mirror complete, not urgently. **No spec risk.**
+
+### Fix C15 — delete the dead `PageCompat#components`
+
+Remove `PageCompat#components` (`page_compat.rb:21-24`); it is shadowed and returns the wrong
+shape if include order ever changes. `page_compat_spec.rb:39-43` asserts `components` is a
+`DataField::Collection` — that stays green (DataFieldAccess provides it). **No spec risk.**
+
+### Fix P5 — add specs (and ideally make two-way) for `SnakeCamelAccess`
+
+At minimum add characterization specs. Consider reusing eco-helpers' polished hash-level
+snake/camel module rather than the bespoke `method_missing` shim (per memory
+`project_snake_camel_access`). Scope decision for Oscar.
+
+### Recommended structural change (kills the class of bug)
+
+Extract a shared `Concerns::V2CollectionContract` (or a `Base::Page::CollectionModel`) that
+defines `get_by_id` (single), `get_by_name`/`get_by_heading`/`get_by_type` (collection, per v2),
+`ordered`, `same_string?(mild:)` **once**, and have DataField/Section/Force/Binding collections
+include it. This turns "one return-type decision per file" into "one contract, four includes" —
+the actual remedy for the ad-hoc philosophy.
+
+---
+
+## 4. Test strategy
+
+### Gem rspec additions (lock the CONTRACT, not the current behaviour)
+- **Return-type contract specs**, one per collection, asserting `get_by_name`/`get_by_heading`
+  return `Array` (C1, C2) and `get_by_id` return a single (C3, C4). Assert `.first` on a
+  multi-match returns the first; assert empty match returns `[]` (not nil) for the collection
+  methods — this is the exact shape act-gov `.first`/`.last` and farmers `.first` depend on.
+- **Add-then-find spec** (C5): `coll.add(id:…){…}; expect(coll.get_by_name(label)).to include(the added)`.
+- **`mild:` parity spec** for `get_by_heading` (C2).
+- **Cross-object consistency meta-spec:** a single spec that asserts all four collections agree
+  on the return type of `get_by_name` (guards against future drift — the root cause here).
+- Update the 9 spec sites listed under Fix-C1 to `.first` in the SAME commit as the fix.
+- Add `SnakeCamelAccess` characterization spec (P5).
+
+### eco-helpers spec additions
+- Update `OozeRedirect#with_fields` (`ooze_redirect.rb:184-189`) and add a spec proving it
+  returns the same shape (Array) whether the field exists or not, against a faithful collection.
+- Regression spec replaying an act-gov-style `get_by_name(...).first` / `.last` through the
+  OozeRedirect path.
+
+### Integration coverage (parity harness, training mini-site)
+- On the all-21-fields template mini-org, run the A/B parity harness (memory
+  `project_parity_test_plan`): execute one representative ooze case using `.get_by_name(...).first`
+  and `.get_by_heading(...).first` against BOTH v2 and GraphQL, assert identical selected field
+  IDs and identical emitted mutation input. **Needs live creds** (mini-site API token) — the only
+  part of this plan that cannot run in CI without secrets.
+- Replay act-gov `20240130_act_disease_title_update_case.rb` (`.first`+`.last`) and the farmers
+  case in `-simulate` mode post-fix to confirm no `.first`-on-single or double-wrap breakage.
+
+---
+
+## 5. Open questions / could not verify
+
+1. **P2/P3 fix status not re-verified.** SYNTHESIS says the IdDiff macro and File/Image/Contractor
+   readers were fixed on this branch; I did not re-open those files this pass. Confirm before
+   relying on them.
+2. **Section weight in the GraphQL fragment.** C6/C14 (order-by-weight) only achievable if the
+   section fragment actually returns a `weight`/ordering field — not confirmed. If absent, response
+   order is the contract and these stay documented gaps.
+3. **`components.add` write path.** Whether an added field can even be created via the current
+   `dataFields.updates`/additions mutation shape without a server-side `buildFromTemplate` ID is a
+   separate question (the collection comment at `collection.rb:47` says it "must reference an
+   existing server-side ID"). Faithful `add` semantics may be bounded by the mutation API.
+4. **Full green-suite baseline.** I did not run `bundle exec rspec`; the 9 spec sites are
+   identified statically. Run the suite before/after to get exact red counts.
+5. **`get_by_type` ordering for components (C7).** v2 does not order components by weight either,
+   so gem matches — but confirm no consumer relies on component order.
+
+---
+
+## Appendix — files inspected
+
+v2 contract: `ecoportal-api-v2/lib/ecoportal/api/v2/page/{components,forces,sections,stages}.rb`,
+`.../page/force/bindings.rb`.
+Gem compat: `lib/.../base/page/data_field/collection.rb`, `.../base/page/section_collection.rb`,
+`.../base/force/{collection,binding_collection,force}.rb`,
+`.../compat/{pages,registers,stage_collection,stage_view}.rb`,
+`.../concerns/{page_compat,data_field_access,snake_camel_access,deprecation}.rb`,
+`.../interface/base_page.rb`.
+Consumers: `multi_org_api/*/config/ooze_cases/*` (grep, ~120 sites),
+`eco-helpers/lib/eco/api/usecases/graphql/compat/ooze_redirect.rb`, `.../ooze_samples/*`.
+Prior findings: `.ai-assistance/code/model_input_mapping/SYNTHESIS.md`.

data/.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md

@@ -4,6 +4,16 @@
 `template-diff-deploy` + `template-maintenance` projects into one plan).
 **Domain reference (read first):** `.ai-assistance/code/template_diff_pairing_domain.md`
 **Code spec:** `.ai-assistance/code/diff_pairing_engine.md`
+**Governing security standard (read before wiring live creds):** `security/ai-service-account-scope`
+in ep-ai-standards. This automation MUST authenticate as a dedicated per-org SERVICE ACCOUNT whose
+grant covers templates/org-config only -- page records (customer data + PII) are structurally out of
+scope, enforced by the credential grant, not by instruction. This is the practitioner discovery point
+for that standard (the template automation is its concrete consumer). The "sandbox creds" in success
+criterion #4 below must be provisioned to that scope. Platform dependency RESOLVED: templates ARE pages
+(`PageUnion`), but `stage.tags` (wrongly deprecated ~21 months ago) has been restored via ecoPortal MR
+!6649, so a rule scoped to template stages can structurally exclude record stages. Defining and
+provisioning the concrete grant is now OUR work (this gem + agent), not a platform blocker -- see the
+service-account grant task in `TODO.md`.
 **Superseded folders (pointers only now):** `template-diff-deploy/`, `template-maintenance/`.
 **Sibling projects:** `qa-services-delivery` (verify), `ooze-graphql-native-migration`,
 `template-csv-pipeline` (memory).

data/.ai-assistance/projects/template-automatic-build-maintenance/TODO.md

@@ -90,6 +90,17 @@ emission layer: an ordered `WorkflowCommand` batch with `placeholderId` threadin
 ---
 
 ## Cross-cutting
+- [ ] **Service-account grant (gates live use; governed by ep-ai-standards `security/ai-service-account-scope`).**
+  This automation must run as a dedicated per-org SERVICE ACCOUNT scoped to templates/org-config only --
+  page records out of scope, enforced by the grant (structural PII/compliance boundary, not instruction).
+  Platform enabler is in place: `stage.tags` (wrongly deprecated ~21 months ago) restored via ecoPortal
+  MR !6649, so a rule scoped to template stages can exclude record stages. OUR remaining work:
+  (a) enumerate in-scope object types (templates; and which of registers / stages / tag defs / workflow +
+  automation config / custom-field defs -- explicit in/out per type, each a potential path back to records);
+  (b) write the concrete `stage.tags` rule and confirm no record stage shares those tags;
+  (c) fix the read/write surface per type (edit templates? read-only org-config?);
+  (d) provision the per-org account and confirm its `canXXX` set carries NO page-record capability.
+  Feeds the "sandbox creds" needed by Phase B2 / Phase 5. Reference: INTENT header + the standard.
 - [ ] Tighten `ecoportal-qa` to consume the gem's page-model instead of its own `TemplateModel`.
 - [ ] Emit `stageId`/`sectionId` back-refs on diff-side `addField`/`addSection` (BUILD already does;
   the diff synthesizer's structural adds still emit only label/placeholder — then threading covers them).