ecoportal-api-graphql 1.3.5 → 1.3.9

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

@@ -0,0 +1,868 @@
+# Search Filters — Code Spec
+
+*Extracted from Insomnia_2026-06-07.yaml — real production queries.*
+*Cross-referenced with Confluence APIDOCS partial filter reference.*
+
+---
+
+## GOTCHA — register search matches on the field's GraphQL DEFINITION key (VERIFIED, 2026-07-02)
+
+A register/field filter matches on the field's **definition key** (e.g. `plain_text.zc366f454`),
+NOT on the field `name:`. Under APIv2 a filter could carry `{ name:, key: }` and v2 resolved the
+field **loosely by name**, so a wrong/stale `key:` still worked. **On GraphQL the literal `key:` is
+used** — a wrong key silently matches nothing (0 results), which for an upsert means "not found →
+create" → **duplicate pages every run**. This bit the jamestrong cans-upsert live (2026-07-01): the
+case hardcoded `plain_text.z5573fdc2` while the real `Identifier:` key is `plain_text.zc366f454`,
+so the existence search never matched and dups accumulated. Always take the field key from a known-
+good source (a working register filter URL / introspection), not an APIv2-era hardcode.
+
+**Exact vs partial (RESOLVED 2026-07-02):** the right op for an exact-id lookup on a plain_text
+field is **`is_filter`** (whole-value equality on the `.exact` keyword subfield) — NOT `match_filter`
+(analyzed/partial, which missed the exact SKU → 0 results) and NOT `exact_filter` (which does not
+exist for plain_text register fields). `contains_filter` is substring (what the UI exposes). The gem
+now translates a v2-style `type: 'exact_filter'` (or `'is_filter'`) → GraphQL `is_filter` with the
+`membranes.<type>` path derived from the key (`Compat::FilterTranslator#translate_exact_filter`).
+CAVEAT: `is_filter` on plain_text is **case-insensitive** and matches only the **first 64 chars**
+(values lowercased + truncated at index). No case-sensitive / >64-char exact op exists. Prefer keying
+integration upserts on `externalId` (server-enforced unique) over data-field search where possible —
+see `ecoPortal_architecture/02_data_model.md`.
+
+---
+
+## Two Query Modalities
+
+### 1. Org search — `currentOrganization { pages(...) }`
+
+```graphql
+query OrgSearchPages(
+  $searchConf:     Search,
+  $templatesOnly:  Boolean,
+  $showHiddenData: Boolean,
+  $first:          Int,
+  $last:           Int,
+  $after:          String,
+  $before:         String
+) {
+  currentOrganization {
+    pages(
+      searchConf:     $searchConf,
+      templatesOnly:  $templatesOnly,
+      showHiddenData: $showHiddenData,
+      first:          $first,
+      last:           $last,
+      after:          $after,
+      before:         $before
+    ) {
+      totalCount
+      pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+      nodes { ...PageUnion }
+    }
+  }
+}
+```
+
+- **Source:** PostgreSQL DB, rendered by API layer
+- **Returns:** `PageUnion` (`BasicPage | PhasedPage`) — full data including `patchVer`,
+  field IDs, all typed data field models
+- **Performance:** ~3s/page on render (slow for large result sets)
+- **Archived:** controlled via `searchConf` filters (e.g. `state_filter` or no filter)
+- **Extra args:** `templatesOnly: Boolean`, `showHiddenData: Boolean`
+- **Best for:** Pre-update fetch, pre-create fetch, finding pages when field IDs are needed
+
+### 2. Register search — `currentOrganization { register(id:) { previewPages(...) } }`
+
+```graphql
+query SearchRegisterPages(
+  $registerId:      ID!,
+  $presetId:        ID,
+  $after:           String,
+  $search:          Search,
+  $includeArchived: Boolean = false
+) {
+  currentOrganization {
+    register(id: $registerId) {
+      previewPages(
+        presetViewId:    $presetId,
+        after:           $after,
+        searchConf:      $search,
+        includeArchived: $includeArchived
+      ) {
+        totalCount
+        pageInfo { endCursor hasNextPage }
+        nodes { ...PreviewPage }
+      }
+    }
+  }
+}
+```
+
+- **Source:** Elasticsearch index (fast — sub-second)
+- **Returns:** `PreviewPage` — field preview values only. **No field IDs, no `patchVer`,
+  no typed field models.** Cannot be used to build mutation inputs.
+- **Archived:** `includeArchived: Boolean` parameter — defaults to `false`, can be `true`
+- **Extra args:** `presetViewId: ID` — applies a register PageView preset configuration
+- **Field name:** `previewPages`, not `pages`
+- **Best for:** Fast lookup of page IDs by metadata before switching to org search
+
+---
+
+## SearchConf Structure
+
+The `searchConf` / `$search` argument type is `Search` — a Hash, not a typed GraphQL
+input model. The top-level structure is:
+
+```json
+{
+  "filters": [ <filter_object>, ... ],
+  "sorters": { "key": "field_name", "direction": "asc" | "desc" },
+  "query":   "optional full-text search string"
+}
+```
+
+**Note on `filters`:** Can be an array of filter objects (standard) or a single filter
+object (observed in some older contractor queries). Prefer array form.
+
+**Note on `sorters`:** Can be a single sorter object or an array. Key field is `key`
+(not `fieldName`).
+
+---
+
+## Filter Operations
+
+All operations are **snake_case strings** in the `operation` field.
+
+### `exact_filter` — equality match
+
+```json
+{
+  "operation": "exact_filter",
+  "params": {
+    "key":   "external_id",
+    "value": "1223"
+  }
+}
+```
+
+Common keys: `external_id`, `state`, `creator_id`, `template_id`
+
+### `date_filter` — date range
+
+```json
+{
+  "operation": "date_filter",
+  "params": {
+    "key":       "updated_at",
+    "gte":       "2025-01-01T00:00:00+00:00",
+    "time_zone": "UTC"
+  }
+}
+```
+
+Params: `key` (field), `gte` (from), `lte` (to), `time_zone`. Date format: ISO8601.
+Common keys: `updated_at`, `created_at`
+
+**Human date mode** — instead of ISO8601 bounds, use a named time window via `mode`:
+
+```json
+{
+  "operation": "date_filter",
+  "params": {
+    "key":       "updated_at",
+    "mode":      "last_month",
+    "time_zone": "Pacific/Auckland"
+  }
+}
+```
+
+Supported modes (from `HumanDateFilterable` concern in backend):
+
+| Category | Modes |
+|---|---|
+| Past relative | `last_year`, `last_quarter`, `last_month`, `last_week` |
+| Past counted | `last_days` (+`days_count`), `last_hours` (+`hours_count`), `last_months` (+`months_count`) |
+| Current period | `current_year`, `current_quarter`, `current_month`, `current_week`, `current_day` |
+| Future relative | `next_year`, `next_quarter`, `next_month`, `next_week` |
+| Future counted | `next_days` (+`days_count`), `next_hours` (+`hours_count`), `next_months` (+`months_count`) |
+| Point-in-time | `exact` (+`days_count`), `less_than` (+`days_count`), `more_than` (+`days_count`), `between` (+`days_count`) |
+| Financial year | `last_financial_year`, `current_financial_year`, `next_financial_year`, `custom_financial_year` (+`year`) |
+| Open-ended | `past`, `future` |
+
+Extra params used with some modes: `days_count`, `hours_count`, `months_count`, `year`, `time_zone` (default: `"Pacific/Auckland"`).
+
+### `register_filter` — scope to one or more registers (org search only)
+
+```json
+{
+  "operation": "register_filter",
+  "params": {
+    "ids": ["registerId1", "registerId2"]
+  }
+}
+```
+
+Use this in the org search to narrow results to a specific register without switching
+to the register-scoped query. Equivalent to `currentOrganization.pages` filtered by register.
+
+### `and_filter` — explicit AND group
+
+```json
+{
+  "operation": "and_filter",
+  "params": {
+    "filters": [
+      { "operation": "exact_filter", "params": { "key": "external_id", "value": "X" } },
+      { "operation": "date_filter",  "params": { "key": "updated_at", "gte": "2025-01-01" } }
+    ]
+  }
+}
+```
+
+Top-level `filters` array is implicitly AND. Use `and_filter` explicitly when nesting
+inside an `or_filter`.
+
+### `or_filter` — OR group
+
+```json
+{
+  "operation": "or_filter",
+  "params": {
+    "filters": [
+      { "operation": "exact_filter", "params": { "key": "external_id", "value": "3333"    } },
+      { "operation": "exact_filter", "params": { "key": "external_id", "value": "TMS00323" } }
+    ]
+  }
+}
+```
+
+### `one_of_filter` — match any value in a set
+
+More concise than an `or_filter` of `exact_filter` calls when matching the same field
+against multiple values.
+
+```json
+{
+  "operation": "one_of_filter",
+  "params": {
+    "key":    "external_id",
+    "values": ["3333", "TMS00323", "ABC-001"]
+  }
+}
+```
+
+Ruby: `SearchConf.new.filter({ operation: 'one_of_filter', params: { key: 'external_id', values: [...] } })`
+
+### `none_of_filter` — exclude all values in a set
+
+```json
+{
+  "operation": "none_of_filter",
+  "params": {
+    "key":    "state",
+    "values": ["inactive", "complete"]
+  }
+}
+```
+
+### `has_any_filter` — field has any non-null/non-empty value
+
+Most common frontend filter. Checks that a field is populated.
+
+```json
+{
+  "operation": "has_any_filter",
+  "params": {
+    "key": "external_id"
+  }
+}
+```
+
+### `match_filter` — full-text / partial text match
+
+For text fields where you want contains/partial matching rather than exact equality.
+
+```json
+{
+  "operation": "match_filter",
+  "params": {
+    "key":   "name",
+    "value": "safety inspection"
+  }
+}
+```
+
+### `exists_filter` / `doesnt_exist_filter` — field presence check
+
+```json
+{ "operation": "exists_filter",        "params": { "field": "external_id" } }
+{ "operation": "doesnt_exist_filter",  "params": { "field": "external_id" } }
+```
+
+Note: uses `field` (not `key`) in params.
+
+### `boolean_filter` — boolean field match
+
+```json
+{
+  "operation": "boolean_filter",
+  "params": {
+    "key":   "archived",
+    "value": true
+  }
+}
+```
+
+### `numeric_range_filter` — numeric range
+
+```json
+{
+  "operation": "numeric_range_filter",
+  "params": {
+    "key": "mould_counter",
+    "gte": 5,
+    "lte": 100
+  }
+}
+```
+
+### `isnt_exact_filter` — negated exact match
+
+```json
+{
+  "operation": "isnt_exact_filter",
+  "params": {
+    "key":   "state",
+    "value": "complete"
+  }
+}
+```
+
+### `not_register_filter` — exclude registers
+
+```json
+{
+  "operation": "not_register_filter",
+  "params": {
+    "ids": ["registerId1"]
+  }
+}
+```
+
+---
+
+## Sorters
+
+```json
+{ "key": "created_at", "direction": "asc" }
+```
+
+Or as an array:
+
+```json
+[{ "key": "created_at", "direction": "desc" }]
+```
+
+Common keys: `created_at`, `updated_at`
+Directions: `"asc"`, `"desc"`
+
+---
+
+## fieldName Reference — Pages
+
+*Extracted from backend filter class analysis (`app/services/new_ep/es/filters/pages/`)
+and frontend `createFilter.ts`. All keys are **snake_case**.*
+
+### Core metadata fields
+
+| fieldName | Supported operations | Values / notes |
+|---|---|---|
+| `external_id` | `exact_filter`, `one_of_filter`, `has_any_filter`, `doesnt_exist_filter` | Unique per org |
+| `state` | `exact_filter`, `one_of_filter`, `isnt_exact_filter` | `"active"`, `"inactive"`, `"complete"` |
+| `name` | `match_filter`, `exact_filter` | Use `match_filter` for text/partial search |
+| `creator_id` | `exact_filter`, `one_of_filter` | PersonMember ID string |
+| `created_at` | `date_filter` | ISO8601 or human mode |
+| `updated_at` | `date_filter` | ISO8601 or human mode |
+| `template_id` | `exact_filter`, `one_of_filter` | Source template MongoDB ID |
+| `id` | `exact_filter`, `one_of_filter` | Page MongoDB ID |
+
+### Location fields
+
+| fieldName | Supported operations | Notes |
+|---|---|---|
+| `location_id` | `exact_filter`, `one_of_filter` | Specific location node — **no** ancestor traversal |
+| `all_location_ids` | `exact_filter`, `one_of_filter`, `has_any_filter` | Includes ancestor location IDs — broader match |
+
+**Prefer `all_location_ids`** when you want "pages assigned to location X or any of its children".
+Use `location_id` only when you need an exact location match with no ancestor roll-up.
+
+### Tag / categorisation fields
+
+| fieldName | Supported operations | Notes |
+|---|---|---|
+| `other_tags` | `exact_filter`, `one_of_filter`, `has_any_filter` | Free-form tag strings |
+| `source` | `exact_filter` | Page source classification |
+| `mould_counter` | `exact_filter`, `numeric_range_filter` | Sequence counter |
+
+### Boolean / presence flags
+
+| fieldName | Supported operations | Notes |
+|---|---|---|
+| `archived` | `boolean_filter`, `exact_filter` | `true` / `false` |
+| `draft` | `boolean_filter`, `exact_filter` | Draft state |
+
+### Sorter fieldNames (common)
+
+| fieldName | Notes |
+|---|---|
+| `created_at` | |
+| `updated_at` | |
+| `name` | Alphabetical |
+| `mould_counter` | Sequence order |
+
+### Operations not currently in `Input::SearchConf`
+
+The backend supports these operations confirmed from production frontend code,
+not yet wrapped as `SearchConf::*` value objects. Pass raw hashes via `SearchConf#filter`:
+
+| Operation | Key param | Use case |
+|---|---|---|
+| `one_of_filter` | `key`, `values` | Match any of N values for one field |
+| `none_of_filter` | `key`, `values` | Exclude N values |
+| `has_any_filter` | `key` | Field has any non-empty value |
+| `match_filter` | `key`, `value` | Partial/full-text match |
+| `exists_filter` | `field` | Field is present in ES document |
+| `doesnt_exist_filter` | `field` | Field is absent |
+| `boolean_filter` | `key`, `value` | True/false field |
+| `numeric_range_filter` | `key`, `gte`, `lte` | Numeric bounds |
+| `isnt_exact_filter` | `key`, `value` | Negated exact match |
+| `not_register_filter` | `ids` | Exclude pages from registers |
+
+Raw hash usage:
+```ruby
+conf = SearchConf.new.filter(
+  { 'operation' => 'one_of_filter', 'params' => { 'key' => 'state', 'values' => ['active', 'complete'] } }
+)
+```
+
+---
+
+## Parametrization Patterns
+
+`SearchConf#with(**substitutions)` returns a cloned `SearchConf` with placeholder
+symbols replaced throughout all nested filters. Use this to build reusable filter
+templates where only target values differ between calls.
+
+### Template for find-by-externalId in any register
+
+```ruby
+FIND_BY_EXT_ID = SearchConf.new
+  .filter(SearchConf::Register.new(:REGISTER_ID))
+  .filter(SearchConf::Exact.new(:external_id, :EXT_ID))
+
+# Instantiate for a specific register + ID
+query_conf = FIND_BY_EXT_ID.with(REGISTER_ID: 'reg_abc', EXT_ID: '1223')
+result = org.pages(searchConf: query_conf.to_h, first: 1)
+```
+
+### Template for date-range sweep with any field
+
+```ruby
+DATE_SWEEP = SearchConf.new
+  .filter(SearchConf::Register.new(:REGISTER_ID))
+  .filter(SearchConf::DateRange.new(:updated_at, gte: :FROM_DATE, lte: :TO_DATE))
+  .sort(:updated_at, :asc)
+
+last_week = DATE_SWEEP.with(
+  REGISTER_ID: 'reg_abc',
+  FROM_DATE:   '2025-06-01T00:00:00+12:00',
+  TO_DATE:     '2025-06-07T23:59:59+12:00'
+)
+```
+
+### Template for multi-state search
+
+```ruby
+ACTIVE_IN_REGISTER = SearchConf.new
+  .filter(SearchConf::Register.new(:REGISTER_ID))
+  .filter(SearchConf::Exact.new(:state, 'active'))
+
+# Reuse across registers — only REGISTER_ID substituted
+reg1_results = ACTIVE_IN_REGISTER.with(REGISTER_ID: 'reg_1')
+reg2_results = ACTIVE_IN_REGISTER.with(REGISTER_ID: 'reg_2')
+```
+
+### Substitution rules
+
+- Placeholder: any Ruby symbol passed as a parameter value (e.g. `:REGISTER_ID`)
+- `with(**kv)` traverses all nested filters recursively and replaces matching symbol keys
+- The original `SearchConf` is never mutated — `with` always returns a fresh clone
+- Substitutions that don't match any placeholder are silently ignored
+
+---
+
+## SearchConf Ruby API — Quick Reference
+
+`Input::SearchConf` is the Ruby value object that builds `searchConf` hashes.
+All classes live under `Ecoportal::API::GraphQL::Input::SearchConf`.
+
+### Wrapped filter classes (produce correct `to_h` output)
+
+| Ruby class | operation string | Constructor |
+|---|---|---|
+| `SearchConf::Exact` | `exact_filter` | `Exact.new(:key, value)` |
+| `SearchConf::DateRange` | `date_filter` | `DateRange.new(:key, gte: iso8601, lte: iso8601, time_zone: 'UTC')` |
+| `SearchConf::Register` | `register_filter` | `Register.new(register_id)` |
+| `SearchConf::And` | `and_filter` | `And.new(filter1, filter2, ...)` |
+| `SearchConf::Or` | `or_filter` | `Or.new(filter1, filter2, ...)` |
+
+### Builder methods on `SearchConf` instance
+
+```ruby
+conf = SearchConf.new
+  .filter(SearchConf::Exact.new(:external_id, 'ABC'))  # add one filter
+  .filter(SearchConf::Register.new('reg_id'))           # chain multiple
+  .sort(:created_at, :desc)                             # add sorter
+  .sort(:name, :asc)                                    # multiple sorters → array
+  .query('search text')                                 # full-text query string
+
+conf.to_h     # → Hash for the searchConf argument
+conf.as_json  # → same (JSON serialisation)
+```
+
+### Common patterns
+
+```ruby
+# Find by externalId in a register
+SearchConf.new
+  .filter(SearchConf::Register.new('REG_ID'))
+  .filter(SearchConf::Exact.new(:external_id, 'ABC-123'))
+
+# Find active pages updated after a date
+SearchConf.new
+  .filter(SearchConf::Register.new('REG_ID'))
+  .filter(SearchConf::Exact.new(:state, 'active'))
+  .filter(SearchConf::DateRange.new(:updated_at, gte: '2025-01-01T00:00:00Z'))
+  .sort(:updated_at, :asc)
+
+# Find pages with one of several externalIds (OR logic)
+SearchConf.new
+  .filter(SearchConf::Or.new(
+    SearchConf::Exact.new(:external_id, 'ABC'),
+    SearchConf::Exact.new(:external_id, 'DEF')
+  ))
+
+# Explicit AND (nesting inside OR — top-level array is already AND)
+SearchConf.new
+  .filter(SearchConf::Or.new(
+    SearchConf::And.new(
+      SearchConf::Exact.new(:state, 'active'),
+      SearchConf::Register.new('REG_1')
+    ),
+    SearchConf::And.new(
+      SearchConf::Exact.new(:state, 'complete'),
+      SearchConf::Register.new('REG_2')
+    )
+  ))
+
+# Reusable template with #with (symbol placeholders)
+TEMPLATE = SearchConf.new
+  .filter(SearchConf::Register.new(:REG_ID))
+  .filter(SearchConf::Exact.new(:external_id, :EXT_ID))
+
+conf = TEMPLATE.with(REG_ID: 'reg_abc', EXT_ID: 'ABC-123')
+```
+
+### For operations NOT yet wrapped (pass raw hash)
+
+```ruby
+# one_of_filter — match any of N values
+SearchConf.new.filter(
+  { 'operation' => 'one_of_filter',
+    'params'    => { 'key' => 'state', 'values' => ['active', 'complete'] } }
+)
+
+# has_any_filter — field is populated
+SearchConf.new.filter(
+  { 'operation' => 'has_any_filter', 'params' => { 'key' => 'external_id' } }
+)
+
+# date_filter with human mode
+SearchConf.new.filter(
+  { 'operation' => 'date_filter',
+    'params'    => { 'key' => 'updated_at', 'mode' => 'last_month', 'time_zone' => 'Pacific/Auckland' } }
+)
+```
+
+All three patterns work: `SearchConf` filters accept filter objects (wrapped classes),
+raw hashes (unwrapped operations), or a mix. `normalize_variables` in `Logic::BaseQuery`
+calls `.to_h` automatically so you never need to call `.to_h` explicitly at the call site.
+
+---
+
+## Production Examples
+
+### Find page by externalId (org search)
+
+```json
+{
+  "showHiddenData": true,
+  "templatesOnly": false,
+  "searchConf": {
+    "filters": [
+      {
+        "operation": "exact_filter",
+        "params": { "key": "external_id", "value": "1223" }
+      }
+    ]
+  },
+  "first": 10
+}
+```
+
+### Find pages in a register updated after a date (org search)
+
+```json
+{
+  "showHiddenData": true,
+  "templatesOnly": false,
+  "searchConf": {
+    "filters": [
+      {
+        "operation": "register_filter",
+        "params": { "ids": ["REGISTER_ID"] }
+      },
+      {
+        "operation": "date_filter",
+        "params": { "key": "updated_at", "gte": "2025-01-01", "time_zone": "UTC" }
+      }
+    ],
+    "sorters": { "key": "created_at", "direction": "asc" }
+  },
+  "first": 5
+}
+```
+
+### Find pages by one of several externalIds (register search — OR logic)
+
+```json
+{
+  "registerId": "REGISTER_ID",
+  "includeArchived": true,
+  "search": {
+    "sorters": { "key": "created_at", "direction": "desc" },
+    "filters": [
+      {
+        "operation": "or_filter",
+        "params": {
+          "filters": [
+            { "operation": "exact_filter", "params": { "key": "external_id", "value": "3333"     } },
+            { "operation": "exact_filter", "params": { "key": "external_id", "value": "TMS00323" } }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Contractor search by externalId (same filter pattern, different query)
+
+```json
+{
+  "searchConf": {
+    "filters": [
+      {
+        "operation": "exact_filter",
+        "params": { "key": "external_id", "value": "9429041280072" }
+      }
+    ]
+  }
+}
+```
+
+### Find pages by state (org search)
+
+Filter by page lifecycle state. The `state` key is snake_case; values are lowercase strings.
+
+```json
+{
+  "searchConf": {
+    "filters": [
+      {
+        "operation": "exact_filter",
+        "params": { "key": "state", "value": "active" }
+      }
+    ]
+  }
+}
+```
+
+**Common state values:** `"active"`, `"inactive"`, `"complete"`
+
+**Find archived pages** — archived pages are a separate flag (`archived: true`), not a state.
+To include archived pages in register search, use `includeArchived: true` on the
+`previewPages` query. For org search, archived pages appear in results by default
+(no separate flag needed — use a state filter if you want to restrict to one state).
+
+**Ruby (SearchConf):**
+```ruby
+SearchConf.new.filter(SearchConf::Exact.new(:state, 'active'))
+```
+
+### Find pages by location ID (org search)
+
+Filter pages associated with a specific location node. The filter key is `location_id`
+(confirmed from Confluence APIDOCS filter reference).
+
+```json
+{
+  "searchConf": {
+    "filters": [
+      {
+        "operation": "exact_filter",
+        "params": { "key": "location_id", "value": "LOCATION_NODE_ID" }
+      }
+    ]
+  }
+}
+```
+
+**Note:** `location_id` targets a single specific node in the location hierarchy.
+To filter by multiple locations, use an `or_filter` wrapping multiple `exact_filter` entries,
+or check whether `in_filter` (listed in Confluence APIDOCS but not yet confirmed via Insomnia)
+is supported.
+
+**Ruby (SearchConf):**
+```ruby
+SearchConf.new.filter(SearchConf::Exact.new(:location_id, 'NODE_ID'))
+```
+
+---
+
+## The Required Pattern: Find Before Mutate
+
+There is no `fetch page by externalId` endpoint. externalId is unique per organisation
+but there is no direct lookup — you must search. The standard workflow:
+
+```ruby
+# Step 1: find the page ID via org search (register-scoped for speed)
+conf = SearchConf.new
+  .filter(SearchConf::Register.new('REGISTER_ID'))   # scope to register
+  .filter(SearchConf::Exact.new(:external_id, 'ABC-123'))
+
+result = org.pages(searchConf: conf.to_h, first: 1)
+page = result.nodes.first
+# page is a PageUnion (BasicPage or PhasedPage) with full data including patchVer + field IDs
+
+# Step 2: build mutation input from the fetched page
+input = Input::Page::Update.from_model(page)
+return if input.nil?  # no changes
+
+# Step 3: update
+payload = api.page.update(input: input)
+```
+
+Why `register_filter` in org search (not register search)?
+- Register search (`previewPages`) is fast/ES but returns `PreviewPage` — no field IDs, no `patchVer`
+- Org search with `register_filter` gives the full `PageUnion` from DB — slow but complete
+- For "does this page exist?" checks, register search is fine. For "update this page", always use org search.
+
+The `register_filter` narrows the org search to one register, which dramatically reduces
+result set size and improves response time despite the ~3s/page DB render cost.
+
+---
+
+## Filter Rules — Silent Failure Traps
+
+**snake_case is mandatory.** Operation names must be snake_case strings (e.g. `exact_filter`,
+`and_filter`). If CamelCase is used (e.g. `ExactFilter`), the server returns **no error and
+no results** — it silently ignores the filter. This is one of the hardest bugs to diagnose.
+
+**`filters` should always be an Array.** The server normalises a single object to an array
+internally, so a bare object happens to work in some endpoints, but always use the array
+form for consistency and forward-compatibility.
+
+---
+
+## Important Observations
+
+### `ArchivePage` — compound mutation pattern
+
+Archiving a page in production runs **two mutations in a single GraphQL request**:
+
+```graphql
+mutation ArchivePage($id: ID!, $blank_external_id: Boolean = true) {
+  updatePage(input: { id: $id, page: { externalId: null } })
+    @include(if: $blank_external_id) {
+    item { ...corePageData }
+  }
+  archivePage(input: { id: $id }) {
+    item { ...corePageData }
+    errors { details fullMessages }
+  }
+}
+```
+
+The `externalId` is blanked first (to prevent duplicate externalId conflicts if the page
+is later unarchived and recreated with the same ID), then the archive mutation runs.
+The `@include(if: $blank_external_id)` directive makes the blank optional.
+
+**Implication for `Mutation::Page::Archive`:** May need to support the combined pattern,
+or at minimum document that callers should blank `externalId` before archiving if they
+manage externalIds.
+
+### Two build patterns
+
+**`Build - Model`** — older pattern, own inline fragment definitions, all 20 data field
+types, no `$content`/`$fields` variables. Gives raw field structure.
+
+**`Build - Standard`** — uses the `CommonPageUnion` fragment with
+`$fields/$content/$only_content` variables. This is the production standard and the
+pattern the gem's `Fragment::Pages::CommonPageUnion` is based on.
+
+### `typo: extact_filter`
+
+One contractor query uses `"operation": "extact_filter"` (typo). The correct name is
+`exact_filter`. The server appears to tolerate this — no results were returned rather
+than an error. Worth noting for the filter builder's validation.
+
+---
+
+## Filter Builder — Operation Constants
+
+*Confirmed from backend source (`app/services/new_ep/es/filters/global/`) and frontend
+`createFilter.ts`. All are valid snake_case operation strings.*
+
+```ruby
+# Core — wrapped by Input::SearchConf::* value objects
+EXACT_FILTER         = 'exact_filter'
+DATE_FILTER          = 'date_filter'
+REGISTER_FILTER      = 'register_filter'
+AND_FILTER           = 'and_filter'
+OR_FILTER            = 'or_filter'
+
+# Confirmed from backend + frontend — pass as raw hash via SearchConf#filter
+ONE_OF_FILTER        = 'one_of_filter'        # match any of N values
+NONE_OF_FILTER       = 'none_of_filter'       # exclude all of N values
+ALL_OF_FILTER        = 'all_of_filter'        # match all values (rarely needed)
+HAS_ANY_FILTER       = 'has_any_filter'       # field has any non-empty value
+MATCH_FILTER         = 'match_filter'         # partial text match
+EXISTS_FILTER        = 'exists_filter'        # field present in ES document
+DOESNT_EXIST_FILTER  = 'doesnt_exist_filter'  # field absent
+BOOLEAN_FILTER       = 'boolean_filter'       # true/false field
+NUMERIC_RANGE_FILTER = 'numeric_range_filter' # numeric gte/lte
+ISNT_EXACT_FILTER    = 'isnt_exact_filter'    # negated exact match
+NOT_REGISTER_FILTER  = 'not_register_filter'  # exclude registers
+
+# Backend-confirmed, frontend-usage only (not typically used in scripts)
+ARCHIVED_FILTER      = 'archived_filter'
+UNARCHIVED_FILTER    = 'unarchived_filter'
+NESTED_FILTER        = 'nested_filter'        # ES nested object query
+ID_FILTER            = 'id_filter'
+PREFIX_FILTER        = 'prefix_filter'
+```
+
+**Previously noted as "not confirmed"** — status now resolved:
+- `exists_filter` — **confirmed** (see above)
+- `in_filter` — **not a real operation**; use `one_of_filter` instead
+- `range_filter` — **not a real operation**; use `date_filter` or `numeric_range_filter`
+- `ne_filter` — **not a real operation**; use `isnt_exact_filter` instead