ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/projects/page-model/DECISIONS.md

@@ -0,0 +1,245 @@
+# Decisions — Page Model Project
+
+---
+
+## 2026-06-07 — Two search modalities: org search vs register search
+
+**Context:** Scripts that need to find pages before updating them have two query paths,
+with fundamentally different data sources, performance profiles, and coverage.
+
+### Org search — `currentOrganization { pages(...) }`
+
+- **Source:** PostgreSQL DB, rendered by the API layer
+- **Returns:** `PageUnion` (`BasicPage | PhasedPage`) — the same model returned by
+  mutations, fully populated from the DB
+- **Performance:** Slow — approximately 3 seconds per page on render due to API-layer
+  data assembly. **Implication:** avoid re-fetching a page after update if possible;
+  the mutation payload already returns the updated `PageUnion`.
+- **Data completeness:** Full — includes `patchVer`, all field values, data field IDs
+  (server-assigned after DB creation), and the full type structure needed for mutations.
+- **Archived pages:** Supported via a query argument — can search archived pages.
+- **Best for:** Pre-update fetch (need `patchVer` + field IDs), post-build-from-template
+  fetch (need server-assigned field IDs to construct create input).
+
+### Register search — `currentOrganization { register(id:) { previewPages(...) } }`
+
+**Correction 2026-06-07 (verified from Insomnia production queries):** The field is
+`previewPages`, not `pages`. Archived pages ARE supported via `includeArchived: Boolean`
+parameter (defaults to `false`).
+
+- **Source:** Elasticsearch (ES) — the org's search index, not the DB
+- **Returns:** `PreviewPage` — field preview values from ES snapshots. No field IDs, no
+  `patchVer`, no typed data field models. Insufficient for building mutation inputs.
+- **Performance:** Fast — sub-second, ES-powered.
+- **Data completeness:** Partial — preview values only. Use to find page IDs, then switch
+  to org search for full data.
+- **Archived pages:** Supported via `includeArchived: Boolean` parameter.
+- **Extra args:** `presetViewId: ID` — applies a register PageView preset configuration.
+- **Best for:** Fast lookup by metadata (`externalId`, state, location tags, date ranges)
+  to get page IDs before switching to org search for full data fetch.
+
+### Search config — `SearchConf` (Hash type)
+
+The `searchConf` argument is not a typed GraphQL model — it is passed as a `Hash`
+(the schema shows it as `Search`). Engineering has backend classes for it but these are
+not exposed as GraphQL input types.
+
+**Verified structure (from Insomnia):**
+
+```json
+{
+  "filters": [ <filter_object>, ... ],
+  "sorters": { "key": "created_at", "direction": "asc" },
+  "query":   "optional full-text string"
+}
+```
+
+**Filter operations (snake_case strings):**
+- `exact_filter` — equality: `{ key: "external_id", value: "X" }`
+- `date_filter` — date range: `{ key: "updated_at", gte: "ISO8601", time_zone: "UTC" }`
+- `register_filter` — scope to registers (org search): `{ ids: ["id1"] }`
+- `and_filter` — explicit AND group: `{ filters: [...] }`
+- `or_filter` — OR group: `{ filters: [...] }`
+
+**Sorter:** `{ "key": "field_name", "direction": "asc"|"desc" }` — note key field is
+`key`, not `fieldName`. Can be a single object or an array.
+
+Full reference with all production examples: `.ai-assistance/code/search_filters.md`
+
+**Reference:** Search filter docs partially exist in Confluence APIDOCS (most common
+filters). Full coverage is pending — see the Search Filter Builder project.
+
+---
+
+## 2026-06-07 — CommonPageUnion: unified fragment for all page integration patterns
+
+**Context:** Customer integration scripts share three fundamental page interaction patterns,
+all of which require reading the full page content (including data field IDs and structure):
+
+1. **Build from template** — After calling `buildFromTemplate`, the server returns a built
+   draft whose data field IDs are already assigned by the DB. Scripts must fetch this draft
+   via `CommonPageUnion` to retrieve those IDs before they can construct the `dataFields`
+   input for the subsequent `createFromTemplate` call.
+
+2. **Fetch before update** — Before calling `updatePage`, scripts must fetch the current page
+   via `CommonPageUnion` to get the current `patchVer` (required for optimistic concurrency)
+   AND the current data field IDs and values. Field IDs change after DB creation and cannot
+   be assumed — they must be read from the live page.
+
+3. **Fetch after create/update** — To confirm the result, scripts re-fetch via
+   `CommonPageUnion` and inspect the returned state.
+
+**Decision:** `Fragment::Pages::CommonPageUnion` is a single, parameterised fragment that
+covers all three patterns. Rather than having separate lightweight/heavyweight variants,
+three boolean query variables control how much is fetched in a given call:
+
+| Variable | Purpose | Use in pattern |
+|---|---|---|
+| `$content` | Include field values, stage completions, people, files | (2) update, (3) verify |
+| `$only_content` | Exclude structural/config fields — content values only | (3) verify result |
+| `$fields` | Include data field definitions (labels, options, structure) | (1) build, (2) update |
+
+**Design rationale — educating customer technicians:** The two-step sequences for create
+and update were deliberately consolidated under one fragment to give customer technicians
+a clear, documented path into the GraphQL integration:
+
+- **CREATE sequence:** (a) `buildFromTemplate` → fetch built draft with `CommonPageUnion`
+  (`$fields: true`) to get data field IDs; (b) fill in values and call `createFromTemplate`.
+- **UPDATE sequence:** (a) fetch current page with `CommonPageUnion` (`$content: true,
+  $fields: true`) to get `patchVer` + current field IDs and values; (b) build update
+  operations and call `updatePage`.
+
+GraphQL's declarative nature (clients specify what they need) is new to many technicians.
+The directive variables make it visible and learnable — they can start with
+`$content: true, $fields: true` to get everything, then dial back once they understand
+what each variable controls.
+
+**Note on Build - Model (legacy pattern):** The Insomnia export contains an older
+`Build - Model` request with its own inline fragment definitions (no `CommonPageUnion`).
+This predates the unified fragment approach. It was used before the team settled on a
+single documented pattern for customer support knowledge sharing. Treat it as legacy;
+all new scripts should use the `Build - Standard` / `CommonPageUnion` approach.
+
+**Note on compound mutations:** The `ArchivePage` Insomnia request runs two mutations in
+one request — `updatePage` (blanks `externalId`) then `archivePage`. This is valid GraphQL
+(multiple operations in one definition, executed in declaration order by the server). It was
+designed for a customer whose middleware was stateless and could not sequence two separate HTTP
+requests within a session. The `operationName` field in the JSON payload identifies the
+primary named definition. This pattern is available to any integration that needs atomic
+sequencing without server-side transactions.
+
+**Reference:** Documented in Jira API Docs space (Confluence APIDOCS).
+Fragment lives at: `lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb`
+Accessed via: `fragment.pages.assemble(:CommonPageUnion)` or via `assemble_fragments`
+when `...CommonPageUnion` appears in a query string.
+
+---
+
+## 2026-06-05 — Page model is phased; DataFields deferred to Phase E
+
+**Context:** Pages are the central EcoPortal entity with 50+ fields, two concrete types
+(BasicPage / PhasedPage), stages, sections, 20 data field types, AI features, and
+workflow. Attempting to implement everything at once is impractical.
+
+**Decision:** Phase the work. Phase A (read) and Phase B (write) cover the core lifecycle
+that customer scripts need. DataFields (Phase E) deferred — they require domain knowledge
+of field types and are unlikely to be needed for structural automation scripts.
+
+**Consequences:** Phase A/B output will not include `dataFields` in mutation inputs.
+Scripts that need to update field values must wait for Phase E.
+
+---
+
+## 2026-06-05 — Page creation requires a template; no blank page mutation exists
+
+**Context:** The schema has no `createPage` mutation. All creation goes via
+`createPageFromTemplate(input: CreateFromTemplateInput!)` or `buildPageFromTemplate`.
+`CreateFromTemplateInput` takes `templateId: ID!` and optionally `dataFields`.
+
+**Decision:** Phase D (creation) is scoped to template-based creation only. No attempt to
+expose a blank-page creation API because none exists on the server.
+
+**Consequences:** Scripts that create pages must know the target template ID. The gem
+should provide a way to look up templates (`Query::Templates`).
+
+---
+
+## 2026-06-05 — Both BasicPage and PhasedPage mapped; Stage deferred to Phase C
+
+**Context:** `PageUnion = BasicPage | PhasedPage`. PhasedPage adds stages; Stage has its
+own `dataFields`, `tasks`, `sections`. Scripting typically works at the Page level (not
+individual stage fields).
+
+**Decision:** Phase A maps `BasicPage` and `PhasedPage` as concrete model classes
+inheriting from `Interface::BasePage`. Stage model populated in Phase C. Scripts can
+access stages via `page.stages` once Phase C is done.
+
+**Consequences:** `PhasedPage#stages` returns raw data (passarray) until Phase C adds a
+proper `Stage` model class.
+
+---
+
+## 2026-06-05 — `patchVer` always queried and always passed on update
+
+**Context:** `patchVer: Int!` is non-null on every page read. The `updatePage` mutation
+accepts it optionally. The server uses it for optimistic concurrency control.
+
+**Decision:** The Page fragment always includes `patchVer`. The `UpdatePage` mutation
+input always includes `patchVer` sourced from the model. This is not optional in our gem
+even though it is optional in the schema.
+
+**Reason:** Silent concurrency failures (last-write-wins without warning) are worse than
+an occasional stale-version rejection. Making `patchVer` mandatory in our usage prevents
+data loss from concurrent edits.
+
+**Consequences:** Any code that builds `UpdatePageInput` must have previously fetched the
+page to get the current `patchVer`. You cannot update a page you haven't read first.
+
+---
+
+## 2026-06-05 — `stageId` in UpdatePageInput: Phase C concern
+
+**Context:** `UpdatePageInput` has `stageId: ID` which targets a specific stage on a
+phased page. Stage-specific operations (submit, review, complete) also use this.
+
+**Decision:** Phase B implements page-level updates only (name, state, locations, tags,
+`patchVer`). Stage-targeting (`stageId`, `submit`, `task` input) is Phase C.
+
+---
+
+## 2026-06-06 — PageUnion implemented as a factory module, not a class
+
+**Context:** The GraphQL `page` and `pages` fields return `PageUnion = BasicPage | PhasedPage`.
+The response wrapping layer calls `response_class.new(data)` and connection node instantiation
+calls `node_class.new(item, parent: self)`. Both require a single "class" that can dispatch to
+the correct concrete type based on `__typename`.
+
+**Decision:** `Model::PageUnion` is implemented as a Ruby module with a custom `.new` method
+that inspects `doc['__typename']` and delegates to `Model::Page::Basic`, `Model::Page::Phased`,
+or `Interface::BasePage` (fallback). It is used as both `item_class` on `Query::Page` and
+`node_class` on `Connection::Page`.
+
+`class_resolver` accepts modules since `resolve_class` uses `Kernel.const_get` for strings and
+returns the constant as-is. The `.new` method passes through `**opts` so `parent:` and `key:`
+from `embeds_many` reach the concrete constructor correctly.
+
+**Consequences:** Callers always receive a concrete `Page::Basic` or `Page::Phased` instance —
+`PageUnion` itself is never instantiated. The `__typename` field must be included in the
+`PageFields` fragment for dispatch to work.
+
+---
+
+## 2026-06-05 — Fragment::Page initial scope
+
+**Context:** `BasePageInterface` has 50 fields. Most are read-only context or authorization
+flags. Customer scripts primarily need identity, state, location, and versioning fields.
+
+**Decision (initial fragment scope):**
+- **Always include:** `id`, `name`, `uid`, `icon`, `patchVer`, `state`, `archived`,
+  `archivedAt`, `draft`, `externalId`, `timeZone`, `otherTags`, `taskPriority`,
+  `sourceTemplateId`, `createdAt`, `updatedAt`, `creatorName`
+- **Locations:** `locations { id name }` (via spread of `LocationNode` fragment)
+- **Exclude initially:** `dataFields`, `sections`, `workflow`, `forces`, `tasks`,
+  `comments`, AI fields, authorization `can*` fields
+
+Fields can be added to the fragment as needed by downstream scripts.

data/.ai-assistance/projects/page-model/TODO.md

@@ -0,0 +1,190 @@
+# TODOs — Page Model Project
+
+> Created 2026-06-05 from live schema introspection.
+> Natural implementation order: A → B → C → D → E
+> Phases C, D, E can be deferred — Phase A + B covers the core script use case.
+
+---
+
+## Phase A — Read (queries, fragment, models)
+
+- [x] **A.1** Fragment::PageFields on BasePageInterface — all initial-scope fields + `...LocationNode`.
+  *Done 2026-06-07 — `lib/ecoportal/api/graphql/fragment/page.rb`*
+
+- [x] **A.2** Interface::BasePage: added `passboolean :draft`, `passthrough :externalId`.
+  *Done 2026-06-07 — archivedAt was already present*
+
+- [x] **A.3** `Base::Page::Basic < Interface::BasePage` (new); `Base::Page::Phased`: added `passarray :stages`.
+  *Done 2026-06-07 — naming follows existing nesting: Base::Page::Basic, Base::Page::Phased*
+
+- [x] **A.4** `Model::Page::Basic < Base::Page::Basic` (new); `Model::Page::Phased` already existed with resolvers.
+  *Done 2026-06-07*
+
+- [x] **A.5** `Query::Page` (single by id); `Model::PageUnion` factory dispatches on `__typename`.
+  *Done 2026-06-07 — PageUnion approach documented in DECISIONS.md*
+
+- [x] **A.6** `Query::Pages` — paginated, `Connection::Page` with `PageUnion` node_class.
+  *Done 2026-06-07*
+
+- [x] **A.7** `Model::Organization`: wired `query :page`, `query :pages`, `query :templates`.
+  *Done 2026-06-07*
+
+- [x] **A.8** `Query::Templates` — reuses `Connection::Page` and `PageFields` fragment.
+  *Done 2026-06-07*
+
+- [x] **A.9** RSpec specs for `Query::Page`, `Query::Pages`, fragment assembly.
+  `spec/ecoportal/api/graphql/query/page_spec.rb` — 7 examples (field_name, accepted_params,
+  item_class, PageFields/LocationNode/BasicPageFields/PhasedPageFields fragment assembly).
+  `spec/ecoportal/api/graphql/query/pages_spec.rb` — 7 examples (field_name, accepted_params,
+  item_class, connection_class, fragment assembly, SearchConf acceptance).
+  *Done 2026-06-07 — 14 examples, 0 failures*
+
+---
+
+## Phase B — Write (update mutation)
+
+- [x] **B.1** `Input::Page` — `name/state/taskPriority/timeZone/externalId/locations/otherTags`.
+  *Done 2026-06-07 — `lib/ecoportal/api/graphql/input/page.rb`*
+
+- [x] **B.2** `Input::Page::Update.from_model` — nested `page:` sub-hash, always injects `patchVer`, supports `publish:` flag.
+  *Done 2026-06-07 — `lib/ecoportal/api/graphql/input/page/update.rb`*
+
+- [x] **B.3** `Mutation::Page::Update` + `Payload::Page::Update` (item via PageUnion).
+  *Done 2026-06-07*
+
+- [x] **B.4** `Mutation::Page::Archive` + `Mutation::Page::Unarchive` + corresponding payloads + inputs.
+  *Done 2026-06-07*
+
+- [x] **B.5** `Builder::Page`: `update/archive/unarchive` methods.
+  *Done 2026-06-07*
+
+- [x] **B.6** `Ecoportal::API::GraphQL#page` → `Builder::Page`.
+  *Done 2026-06-07*
+
+- [x] **B.7** RSpec specs: `Input::Page::Update.from_model` (no-change nil, patchVer, publish, clientMutationId); `Model::PageUnion` __typename dispatch.
+  *Done 2026-06-07 — archive/unarchive input specs deferred (low value, straightforward passthrough)*
+
+---
+
+## Phase C — PhasedPage stages
+
+> Prerequisite: Phase A model classes exist.
+
+- [x] **C.1** Populate `Base::Page::Phased::Stage` with fields from `Stage` type:
+  `id`, `name`, `ordering`, `state`, `active`, `started`; predicate methods `active?`/`started?`;
+  `sections` → SectionCollection, `components` → DataField::Collection, `[]` hash-style access.
+  *Done 2026-06-07 — 17 specs in `spec/ecoportal/api/graphql/base/page/phased/stage_spec.rb`*
+
+- [x] **C.2** Add `embeds_many :stages, klass: Stage` on `Base::Page::Phased`.
+  *Done 2026-06-07 — `Compat::StageCollection#coerce_stage` wraps raw hashes in `Stage`*
+
+- [x] **C.3** Add `stageId` support to `Input::Page::Update` and `Mutation::Page::Update`
+  for stage-targeted updates.
+  *Done 2026-06-07 (commit 6305f69) — stageId + submit kwargs; non-nil result for stage-only submit*
+
+- [x] **C.4** Add submit/review task mutations: `approveReviewPageTask`, `rejectReviewPageTask`,
+  `batchUpdateReviewPageTask`, `restartReviewPageTask`, `undoReviewPageTask`.
+  `Input::Page::ReviewTask` (id, stageId, comment); `Payload::Page::ReviewTask` (item: PageUnion);
+  5 mutation classes; `Builder::Page` wired with `approve/reject/restart/undo/batch_update_review_task`.
+  *Done 2026-06-07 — 5 specs in `spec/ecoportal/api/graphql/input/page/review_task_spec.rb`*
+
+---
+
+## Phase D — Creation from template
+
+- [x] **D.1** `Input::Page::CreateFromTemplate` — `templateId`, `showHiddenData`, `stageId`,
+  `submit`, `attach`, `draft`, `clientMutationId`, `dataFields` (raw passthrough), `page` (embeds_one).
+  *Pre-existing*
+
+- [x] **D.2** `Mutation::Page::CreateFromTemplate` — `createPageFromTemplate`, `CreateFromTemplateInput!`.
+  *Pre-existing*
+
+- [x] **D.3** `Mutation::Page::BuildFromTemplate` — `buildPageFromTemplate`, `BuildFromTemplateInput!`.
+  *Pre-existing*
+
+- [x] **D.4** Draft lifecycle mutations — all share `Payload::Page::Draft` (item: PageUnion):
+  - `Input::Page::CreateDraft` (templateId), `Mutation::Page::CreateDraft` (createPageDraft)
+  - `Input::Page::DeleteDraft` (id), `Mutation::Page::DeleteDraft` (deleteDraftPage)
+  - `Input::Page::PublishDraft` (id), `Mutation::Page::PublishDraft` (publishDraftPage)
+  *Done 2026-06-07 — 4 specs in `spec/ecoportal/api/graphql/input/page/create_draft_spec.rb`*
+
+- [x] **D.5** `Builder::Page` wired for all template + draft operations:
+  `build_from_template`, `create_from_template`, `create_draft`, `delete_draft`, `publish_draft`.
+  *Done 2026-06-07*
+
+---
+
+## Phase E — DataFields (deferred — complex)
+
+> DataFields are the rich content of pages (form fields). 20 field types.
+> Defer until Phases A–D are stable and there is a clear script use case.
+
+- [x] **E.1** All 20 DataField types implemented in `lib/ecoportal/api/graphql/base/page/data_field/`.
+  10 writable types (PlainText, RichText, Date→DateField, Number, Gauge, Select, Checklist,
+  TagField, People, Geo, ContractorEntities, CrossReference, File→FileField, ImageGallery).
+  6 read-only stubs (Signature, Mailbox, ActionsList, Law, AiSummary, Table).
+  TYPE_MAP covers all 20 `__typename` → Ruby class mappings.
+  *Done 2026-06-08 — 68 examples in data_field_spec.rb*
+
+- [x] **E.2** `DataFieldOneToManyInput { additions, updates, deletions }` fully wired:
+  `Collection#mark_for_deletion` + `#dirty_deletions`; `DataFieldAccess#data_fields_deletions`;
+  `Input::Page::Update.from_model` includes deletions in `build_data_fields`.
+  *Done 2026-06-08*
+
+- [x] **E.3** Data field access wired on all page models via `Concerns::DataFieldAccess`
+  included in `Interface::BasePage` (`components`, `field_collection`, `data_fields_updates`,
+  `data_fields_additions`, `data_fields_deletions`). Stage exposes `components` via sections.
+  *Pre-existing + additions from E.2*
+
+- [x] **E.4** Code-spec doc: `.ai-assistance/code/data_fields.md` — all 20 types, setter API,
+  Collection API, DataFieldOneToManyInput wiring, stage-level access, spec coverage table.
+  *Done 2026-06-08*
+
+---
+
+## Cross-cutting
+
+- [x] **X.1** `Fragment::BasicPageFields on BasicPage` — sections (id, heading, __typename).
+  *Done 2026-06-07 — fragment/page.rb*
+
+- [x] **X.2** `Fragment::PhasedPageFields on PhasedPage` — stagesIndex, currentStage, activeStages.
+  *Done 2026-06-07 — fragment/page.rb*
+
+- [x] **X.3** `Query::PageDelta` — `pageDelta(deltaInput: [DeltaInput!]!, searchConf: Search)`.
+  Actual schema: takes `{ id, deltaAt: ISO8601DateTime! }` per page, not just ids.
+  Returns `[DeltaResult]` (UPDATED/NOT_FOUND/NEW). `Base::DeltaResult`, `Input::DeltaInput`.
+  *Done 2026-06-07*
+- [x] **X.4** CHANGELOG and version bump — done 2026-06-07, bumped to 1.4.0.
+- [x] **X.5** Cycle-end Gemini review — done 2026-06-07. Finding applied: PAGE_FIELD_KEYS
+  single source of truth in Input::Page.
+
+---
+
+## Search integration
+
+> Two modalities — see DECISIONS.md "Two search modalities" entry for full comparison.
+
+- [x] **S.1** Wire `Query::Pages` (org search) for pre-update fetch workflow:
+  documented in `search_filters.md` ("The Required Pattern: Find Before Mutate") and
+  as a code comment on `Query::Pages`. `RegisterPreviewPages` is insufficient — no
+  `patchVer` or field IDs. Both docs explain the required pattern.
+  *Done 2026-06-07*
+
+- [x] **S.2** `Query::RegisterPreviewPages` + `Base::PreviewPage` + `Connection::PreviewPage`.
+  *Done 2026-06-07 — fast ES search, includeArchived supported, presetViewId supported*
+
+- [~] ~~Wire register-scoped page search — `Query::RegisterPreviewPages`:~~
+  `currentOrganization { register(id: $id) { previewPages(searchConf: $conf, includeArchived: $includeArchived, presetViewId: $presetId, ...) } }`
+  Returns `PreviewPage` nodes (ES-backed, fast). No field IDs or `patchVer`.
+  Supports archived pages via `includeArchived: Boolean` (default false).
+  Useful for fast metadata lookup before switching to org search for full data.
+
+- [x] **S.3** `.ai-assistance/code/search_filters.md` — complete filter reference.
+  Extracted from Insomnia_2026-06-07.yaml (real production queries) + Confluence APIDOCS.
+  Covers: find by externalId ✓, find by state ✓, find by location_id ✓, find by date range ✓,
+  nested AND/OR ✓. Also documents: two query modalities, SearchConf structure, silent failure
+  traps, compound archive pattern, operation constants.
+  *Done 2026-06-07*
+
+- [ ] **S.4** Full search filter builder — see dedicated project:
+  `.ai-assistance/projects/search-filter-builder/`

data/.ai-assistance/projects/search-filter-builder/INTENT.md

@@ -0,0 +1,107 @@
+# Project: Search Filter Builder
+
+**Created:** 2026-06-07
+**Status:** Planning
+
+---
+
+## Problem
+
+The EcoPortal GraphQL `searchConf` argument is a Hash type — not a typed GraphQL input
+model. This means:
+- No schema validation or autocomplete for filter structures
+- Scripts must hand-craft raw hashes, which are error-prone and hard to read
+- No reuse: changing a search target (e.g. a different `externalId`) requires cloning
+  and mutating the whole hash manually
+- No discoverability: customers have no way to learn available filter fields from the
+  schema — they must consult separate documentation
+
+Engineering has backend classes for the search model, but these are not exposed as
+GraphQL input types. The Confluence API Docs space has a partial filters reference, but
+it is incomplete and not tied to any code.
+
+---
+
+## Goal
+
+Provide a first-class Ruby filter builder in `ecoportal-api-graphql` that:
+
+1. **Mirrors backend structure** — classes that correspond to the backend search model,
+   even though they have no GraphQL type equivalent (they serialise to the expected Hash).
+2. **Supports AND/OR composition** — clean DSL to express nested filter logic without
+   manually constructing the `or:` / `filters:` nesting.
+3. **Supports parametrization** — re-use a filter template by substituting specific
+   values (e.g. swap `externalId`, `locationId`, field value) without re-building
+   from scratch each call.
+4. **Works for both search modalities:**
+   - Org search: `currentOrganization { pages(searchConf: ...) }`
+   - Register search: `currentOrganization { register(id:) { pages(searchConf: ...) } }`
+5. **AI assistance hook (future):** The front-end already has AI-generated filter
+   construction for end users. This builder should be designed so that a future AI layer
+   can generate filter objects from natural-language descriptions. The structured classes
+   make this tractable — the AI outputs typed objects rather than raw hashes.
+
+---
+
+## Context
+
+### searchConf structure (verified from Insomnia production queries)
+
+```json
+{
+  "filters": [ <filter_object>, ... ],
+  "sorters": { "key": "created_at", "direction": "asc" },
+  "query":   "optional full-text string"
+}
+```
+
+`filters` can be an array (standard) or a single object (older queries).
+`sorters` can be a single object or an array. Key field is `key` (not `fieldName`).
+
+### Filter operations (snake_case strings — confirmed)
+
+| Operation | Structure | Notes |
+|---|---|---|
+| `exact_filter` | `{ key: "field", value: "val" }` | Equality match |
+| `date_filter` | `{ key: "field", gte: "ISO8601", time_zone: "UTC" }` | Also: `lte` |
+| `register_filter` | `{ ids: ["id1", "id2"] }` | Org search only — scope to registers |
+| `and_filter` | `{ filters: [...] }` | Explicit AND group (implicit at top level) |
+| `or_filter` | `{ filters: [...] }` | OR group |
+
+Additional (from Confluence docs, not yet confirmed via Insomnia):
+`in_filter`, `range_filter`, `exists_filter`, `ne_filter`
+
+### Known filter key fields (confirmed from Insomnia)
+
+| key | Type | Operations confirmed |
+|---|---|---|
+| `external_id` | string | `exact_filter` |
+| `updated_at` | datetime | `date_filter` |
+| `created_at` | datetime | (in sorters; likely filterable too) |
+
+Additional (from Confluence docs): `state`, `location_ids`, `creator_id`, `template_id`
+
+Full reference with production examples: `.ai-assistance/code/search_filters.md`
+
+### Source references
+
+- Insomnia v5 export: pending import into `.ai-assistance/tmp/insomnia_searches.json`
+- Backend filter classes: accessible via the ecoPortal Rails codebase
+- Front-end queries: `.graphql` files distributed across the React codebase hierarchy
+- Confluence APIDOCS: partial filter reference (most common filters section)
+
+---
+
+## Design principles
+
+- **No GraphQL type required:** Builder classes serialise to Hash — they are plain Ruby
+  value objects, not GraphQL input classes. No `Logic::Input` inheritance needed.
+- **Composable:** `AndFilter`, `OrFilter`, `Filter`, `Sorter`, `SearchConf` as
+  distinct classes. Compose like: `SearchConf.new.where(externalId: 'X').or(state: :active, state: :draft)`.
+- **Parametrizable:** A built `SearchConf` can be cloned with substitutions —
+  `search.with(externalId: 'Y')` returns a new instance with one value swapped.
+- **Serializes to Hash:** `search.to_h` returns the raw hash ready to pass as
+  `searchConf:` argument to any query.
+- **AI-compatible (future):** Class structure is simple enough for an AI model to
+  instantiate from a natural-language description. The AI assistance integration
+  is a follow-on — design should not be blocked by it.

data/.ai-assistance/projects/search-filter-builder/TODO.md

@@ -0,0 +1,131 @@
+# TODOs — Search Filter Builder
+
+> Natural order: 1 → 2 → 3 → 4 → 5. Step 1 unblocks everything else.
+
+---
+
+## Step 1 — Ground truth: gather filter fieldNames and operator examples
+
+- [x] **1.1** Insomnia v5 export reviewed — all search patterns documented in
+  `.ai-assistance/code/search_filters.md`. Confirmed operations: exact_filter,
+  date_filter, register_filter, and_filter, or_filter (all snake_case).
+  *Done 2026-06-07*
+
+- [x] **1.2** Backend filter classes read — `app/services/new_ep/es/filters/`.
+  Key findings: 29 global filter operations via dynamic class routing (operation →
+  `"#{op.camelize}Filter"` class name); no central whitelist — filters auto-discovered.
+  Page-specific fieldNames: external_id, state, name, creator_id, created_at, updated_at,
+  template_id, id, location_id, all_location_ids, other_tags, archived, draft, mould_counter.
+  Full human date mode list extracted from `HumanDateFilterable` concern.
+  *Done 2026-06-08*
+
+- [x] **1.3** Frontend `.graphql` + `createFilter.ts` swept — 159 unique operations found.
+  New operations confirmed beyond prior Insomnia list: `one_of_filter`, `none_of_filter`,
+  `has_any_filter`, `match_filter`, `exists_filter`, `doesnt_exist_filter`, `boolean_filter`,
+  `numeric_range_filter`, `isnt_exact_filter`, `not_register_filter`.
+  Confirmed `in_filter`/`range_filter`/`ne_filter` are NOT real operations.
+  *Done 2026-06-08*
+
+- [x] **1.4** `search_filters.md` extended with:
+  - Full fieldName reference table for Pages (core metadata, location, tag, boolean fields)
+  - Extended operation reference (15 confirmed operations including new ones)
+  - Human date mode table (30+ modes from HumanDateFilterable)
+  - Parametrization patterns section (SearchConf#with — 3 examples)
+  - Updated Filter Builder constants with confirmed/denied status
+  *Done 2026-06-08*
+
+---
+
+## Step 2+3 — Design + Implement (Done 2026-06-07)
+
+- [x] **2.1+3.1** Implemented `Input::SearchConf` with nested filter classes:
+  `SearchConf::Exact`, `SearchConf::DateRange`, `SearchConf::Register`,
+  `SearchConf::And`, `SearchConf::Or`. Plain Ruby value objects, no Logic::Input.
+  Chainable builder, `to_h` serialises to the expected Hash structure.
+  `as_json` support for transparent JSON serialisation.
+  *`lib/ecoportal/api/graphql/input/search_conf.rb`*
+
+- [x] **2.2+3.3** Parametrization via `#with(**substitutions)` — returns a cloned
+  `SearchConf` with substituted values propagated into nested filters.
+  *Confirmed immutable (original not mutated)*
+
+- [x] **4.1** 23 RSpec specs covering all filter types, builder methods, sorter
+  single/array convention, parametrization, nested Or propagation, as_json.
+  *`spec/ecoportal/api/graphql/input/search_conf_spec.rb`*
+
+## Remaining
+
+- [x] **3.4** Wire `SearchConf` acceptance into queries — implemented via
+  `Logic::BaseQuery#normalize_variables`: auto-calls `.to_h` on any value responding to `to_h`
+  before passing as GraphQL variables. All queries accept `SearchConf` directly.
+  *Done 2026-06-07 (commit cc72902)*
+
+- [ ] **5.1 — Fluent DSL (future):** Replace the explicit constructor API with a fluent
+  operator-based DSL using Ruby's `&` (AND) and `|` (OR) operators — similar to how
+  Arel/Sequel work. Proposed syntax:
+
+  ```ruby
+  # Simple field predicate
+  Search[:external_id].eq('ABC')
+  Search[:updated_at].since('2025-01-01')
+  Search[:state].is(:active)
+
+  # Compound (& = AND, | = OR — operator precedence is natural)
+  Search[:external_id].eq('ABC') & Search.in_register('REG_ID')
+
+  Search[:state].is(:active) | Search[:state].is(:draft)
+
+  # Complex: register + date AND (state active OR draft)
+  Search.in_register('REG_ID') &
+  Search[:updated_at].since('2025-01-01') &
+  (Search[:state].is(:active) | Search[:state].is(:draft))
+
+  # Parametrize via .with
+  base = Search[:external_id].eq('X') & Search.in_register('REG')
+  copy = base.with(external_id: 'Y')
+  ```
+
+  Implementation: `Search[]` returns a `FieldRef` object; `.eq`, `.is`, `.since`,
+  `.contains` return filter value objects; `&` and `|` return `And`/`Or` composites.
+  Everything still serialises via `to_h`. The current explicit API (`SearchConf::Exact.new`)
+  remains as the foundation — the DSL is a layer on top.
+
+  **Why operator-based over method-chain (`filter.or.attr.label.contains(...)`):**
+  - `&`/`|` have natural Ruby precedence — parentheses control grouping as expected
+  - No ambiguity between "start a new filter" vs "modify current filter"
+  - Composable: any sub-expression can be stored in a variable and reused
+  - Familiar to developers who know Arel, Sequel, or Mongoid
+
+  **AI-generation hook:** The structured DSL makes AI output easy to validate —
+  the AI emits `Search[:field].op(value)` expressions that can be parsed/verified
+  before execution.
+
+## ~~Steps 2–4~~ — Done (superseded by implementation)
+
+Steps 2–4 were planning artefacts written before implementation. All are complete:
+- `SearchConf`, `SearchConf::Exact/DateRange/Register/And/Or/RawFilter` — implemented
+- `#to_h`, `#with`, `normalize_variables` auto-`to_h` — implemented
+- 23 RSpec specs covering all types — implemented
+- `search_filters.md` code-spec — implemented
+- Fluent DSL (`SearchConf[:field].eq(v)`, `&`, `|`) — implemented 2026-06-08
+
+---
+
+## Step 5 — AI filter generation
+
+- [x] **5.1** Prompt template designed — system prompt in `SearchConf::AIGenerator::SYSTEM_PROMPT`:
+  all 13 operations with params, 11 page fieldNames with types/values, snake_case rule,
+  instruction to use `date_filter mode:` for relative dates.
+  *Done 2026-06-09*
+
+- [x] **5.2** `SearchConf.from_description(text, api_key:, model:, register_id:, context:, validate:)`.
+  Claude tool use (structured output via `build_search_conf` JSON schema).
+  `SearchConf::AIGenerator` in `input/search_conf/ai_generator.rb`.
+  Lazy require — `anthropic` gem not a hard dependency; helpful LoadError if missing.
+  `.env` loaded automatically in `spec_helper.rb` via dotenv.
+  Live tests tagged `:live`: `bundle exec rspec ...ai_generator_spec.rb --tag live`
+  *Done 2026-06-09*
+
+- [ ] **5.3** Evaluate: compare AI-generated filters against hand-crafted equivalents
+  using the Insomnia sample set as ground truth. Run live tests, collect outputs,
+  compare to manually built `SearchConf` instances.