ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/code/ecoPortal_architecture/13_ai_infrastructure.md

@@ -1,183 +0,0 @@
-# 13 — AI Infrastructure
-
-*Extracted from backend source analysis of `C:\docker\ecoPortal_master` (2026-06-08).*
-*This is **customer-facing** infrastructure — not to be reused for internal tooling.*
-
----
-
-## Overview
-
-EcoPortal's AI layer is built on AWS Bedrock (primary LLM and embeddings) + OpenSearch KNN
-(vector search) + AWS Bedrock AgentCore (natural language → filters). GCP Vertex AI provides
-a fallback for image analysis. All AI features are organisation-scoped and gated by feature flags.
-
----
-
-## LLM Models (AWS Bedrock)
-
-| Model ID | Region | Use case |
-|---|---|---|
-| `anthropic.claude-3-5-sonnet-20241022-v2:0` | `ap-southeast-2` | AiSummary generation, Image OCR/metadata, SmartFill |
-| `anthropic.claude-3-sonnet-20240229-v1:0` | inferred | Legacy AiSummary |
-| `meta.llama3-3-70b-instruct-v1:0` | `us-east-2` | Alternative LLM |
-| `amazon.nova-micro-v1:0` | `us-east-1` | Lightweight inference (980 req/min rate limit) |
-
-**Guardrails (prompt injection protection):**
-- `us-east-2`: guardrail ID `7gsue70cel0j` v1 (`prompt_attack_only`)
-- `ap-southeast-2`: guardrail ID `5mg9t3aqm3ic` v1 (`prompt_attack_only`)
-
-Rate limiting: Redis-backed sorted sets. Claude 3: 90 req/min; Nova Micro: 980 req/min.
-
----
-
-## Embedding Models (AWS Bedrock Cohere)
-
-| Model ID | Env var | Dimensions | Region | Use case |
-|---|---|---|---|---|
-| `cohere.embed-multilingual-v3` | `COHERE_EMBED_V3_MODEL_ID` | 1024 | `ap-southeast-2` | Universal embeddings |
-| `us.cohere.embed-v4:0` | `COHERE_EMBED_V4_MODEL_ID` | 1024 (default) | `us-east-1` | High-perf embeddings |
-
-Max batch: 96 texts/call. Used for: page text field vectors, template descriptions, semantic search.
-
----
-
-## AI-Powered Features
-
-### 1. AiSummary Field (`NewEp::Pages::DataFields::AiSummary`)
-
-AI-generated text summary field on pages. Template-configured.
-
-**Gem type:** `Base::Page::DataField::AiSummary` (read-only in DataFieldInput)
-**Dedicated mutations:** `generateAiSummary`, `submitAiSummaryFeedback`
-
-Key fields:
-- `instructions` — custom prompt addition set on the template field (**reviewable by team**)
-- `trigger` — `submitted` | `approved` (when generation fires)
-- `triggerStageIds` — stages that trigger (empty = all)
-- `textFormat` — `simple_text` | `bullet_points` | `numbered_list` | `headings`
-- `aiSummary` — the generated text
-- `alreadyRated` — whether the user has given feedback
-
-Versioning: `NewEp::Pages::AiSummaryVersion` tracks prompt, token counts, status, ratings.
-
-### 2. SmartFill Field (`NewEp::Pages::DataFields::SmartFill`)
-
-AI-auto-populated data fields using template-defined prompts. Supports plain text, date,
-select, rich text, mailbox, actions list field types.
-
-**Gem type:** `Base::Page::DataField::SmartFill` (read-only in DataFieldInput)
-**Dedicated mutations:** `generateSmartFill`, `submitSmartFillFeedback`
-
-Key fields:
-- `instructions` — the AI prompt for this field (**reviewable by team**)
-- `trigger_type` — `manual` | `snapshot` | `live`
-- `status` — `pending` | `generating` | `success` | `failed`
-- `edit_enabled` — whether users can override the AI-generated value
-- `generated_at` — timestamp
-
-### 3. Template AI Description
-
-Templates can have an auto-generated AI description used for semantic search.
-
-- Field: `ai_description` on `Enzyme::Mould`
-- Embeddings: `ai_description_embeddings` (Cohere v4, 1024 dims)
-- Job: `NewEp::Pages::Templates::AiDescriptionEmbedJob`
-- Query log: `NewEp::Pages::Templates::AiQueryLog`
-
-### 4. Semantic Search (OpenSearch KNN)
-
-Vector-based page search on `text_field_vectors.embedding` (nested field).
-
-- Index: Enzyme::Ooze + NewEp::Page
-- Vector path: `text_field_vectors.embedding`
-- Dimensions: 1024 (Cohere v4)
-- Min score: 0.65, KNN k: 10
-- Gated by: `organization.pages_semantic_search_enabled?`
-- Service: `NewEp::Es::SemanticQs::Page`
-
-### 5. Smart Search — Natural Language → Filters
-
-Converts a user's natural-language query into structured register search filters.
-
-- Service: `NewEp::GeneratedFilters::PageFilters::Generate`
-- Backend: `AwsBedrock::AgentCore::InvokeAgentRuntime`
-- Agent ARN: `arn:aws:bedrock-agentcore:ap-southeast-2:697073004009:runtime/prod_master_page_filters_agent-P10hX5HEIG`
-- Auth: JWT tokens via `NewEp::AgentSessions::TokenService` (scope: `page_filters_agent`)
-- Dev endpoint: `http://host.docker.internal:8080/invocations` or `SMART_QUERY_AGENT_URL`
-
-This is the backend for the "build register filters on the go" customer feature.
-
-### 6. Image OCR / Metadata Extraction
-
-Extracts text, captions, descriptions, and sensitivity flags from uploaded images.
-
-**Primary:** AWS Bedrock Claude 3.5 Sonnet (`ap-southeast-2`)
-**Fallback:** GCP Vertex AI Gemini (`gemini-3.1-flash-lite`)
-
-Supported formats: PNG, JPG, JPEG, GIF, WebP, BMP
-Max size: 4.71 MB (Bedrock), 19 MB (GCP); Max resolution: 1568px / 1.15 MP
-
-Output: `description`, `caption`, `extracted_text`, `sensitive_content`, `overall_confidence`
-
-### 7. Inline Text AI Tools
-
-General text manipulation operations accessible from any text-capable field.
-
-**Model:** GCP Vertex AI Gemini (`gemini-3.1-flash-lite`)
-**Mutations:** `aiToolsSummarize`, `aiToolsFixSpellingGrammar`, `aiToolsMakeFormal`,
-`aiToolsRephrase`, `aiToolsTranslate`
-
-Context injection: field label, description, max char limit (via `AiTools::ContextInput`).
-Translation backend: Google Cloud Translate.
-
----
-
-## Video Transcription
-
-Not implemented. The application uses vision models (image OCR) but no video
-transcription pipeline was found in the codebase. Status: not available.
-
----
-
-## Async Job Queue
-
-| Job | Queue | Purpose |
-|---|---|---|
-| `NewEp::Pages::DataFields::AiSummaryGenerationJob` | `p3` | Generate AI summary (max 3 retries) |
-| `NewEp::Pages::DataFields::AiSummaryTriggerJob` | async | Trigger on page submit/approve |
-| `Kickstand::NewEp::Pages::AiSummaryCreateVersionJob` | Kickstand | Create version record on stage submission |
-| `NewEp::Pages::Templates::AiDescriptionEmbedJob` | `p3` | Embed template description (Cohere v4) |
-| `Kickstand::NewEp::Pages::GenerateFieldEmbeddingsJob` | Kickstand | Embed page text field content |
-
----
-
-## AI Prompt Instructions — Team Review Note
-
-Both `AiSummary` and `SmartFill` fields store an `instructions` string that is appended
-to Bedrock's system prompt at generation time. These instructions are set by template
-builders (human, in-app) and directly influence output quality and safety.
-
-**Current situation:**
-- No workflow exists in the gem or backend for auditing/reviewing these prompts at scale.
-- Instructions are stored per-field-instance in the page document.
-- To review: query pages that have AiSummary/SmartFill fields and read the `instructions` field.
-
-**Future work needed:**
-- A review/approval workflow for template-level AI field instructions
-- Possibly surfacing instructions in the template admin UI for bulk review
-- Tracked in: `projects/TODO.md` — "AI prompt review workflow"
-
----
-
-## Dependencies (Gemfile)
-
-```ruby
-gem 'aws-sdk-bedrockruntime', '~> 1.39'    # LLM invocation
-gem 'aws-sdk-bedrockagentcore', '~> 1.14'  # Agent (smart search)
-gem 'opensearch-ruby'                       # Vector search
-gem 'faraday_middleware-aws-sigv4'          # AWS SigV4 auth
-gem 'google-cloud-translate', '3.6.1'       # Translation for AI tools
-gem 'memo_wise'                             # Embedding memoisation
-gem 'image_processing', '~> 1.2'           # Image resizing
-gem 'ruby-vips', '~> 2'                    # Image processing backend
-```

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

@@ -1,240 +0,0 @@
-# EcoPortal GraphQL Schema — AI Agent Quick Reference
-
-**Source:** Live introspection `20260605T101224_live_ep_graphql_schema.graphql.json`
-**Use this doc to:** orient quickly on the schema without re-running extraction scripts.
-
----
-
-## Architecture at a Glance
-
-```
-Query {
-  currentOrganization: Organization!   ← ALL org data lives here
-  checkInConfig(identifier:)           ← public kiosk endpoint (no auth)
-  publicPage / publicTemplate          ← anonymous access
-  user / users                         ← user management
-  kickstand*                           ← workflow automation
-}
-```
-
-**Everything important is nested under `currentOrganization`.**
-There are no top-level `page`, `action`, or `contractorEntity` query fields —
-you always go through `currentOrganization.page(id:)`, etc.
-
----
-
-## Mutation Pattern — Consistent Across All Mutations
-
-**All 161 mutations use a single `input: SomeType!` wrapper.** No mutation has
-separate top-level arguments. This is consistent — build your gem input classes
-as `InputClass.from_model(model)` returning a hash that maps to the single `input:` arg.
-
-```graphql
-mutation UpdateSomething($input: UpdateSomethingInput!) {
-  updateSomething(input: $input) { item { ...fields } errors { ... } }
-}
-```
-
----
-
-## Schema-Wide Shared Patterns
-
-### `patchVer: Int!` — Optimistic Concurrency Lock
-Present on: `BasePageInterface`, `CheckInConfig`
-- **Non-null on read** — every page/kiosk config response includes it.
-- **Optional on write** (mutation input) — but should always be passed.
-- **Pattern:** read `patchVer` from model → include in update input → server rejects if stale.
-- **Gem:** `BasePage` maps it as `passthrough :patchVer`. Not yet injected in mutation inputs.
-
-### `IdDiffInput` — Incremental Relationship Updates
-```graphql
-input IdDiffInput { additions: [ID!], removals: [ID!] }
-```
-Used for array relationships in **update** mutations (not create). Create mutations use `[ID!]` flat arrays.
-
-Always build separate `Create` and `Update` input classes for areas using `IdDiffInput`.
-
-### `OneToManyInput` — Nested Object Arrays
-```graphql
-input DataFieldOneToManyInput { additions: [DataFieldInput!], updates: [DataFieldInput!], deletions: [ID!] }
-```
-Pattern for complex nested array updates. Present for: `dataFields`, `visitorTypeConfigurations`,
-`requirements`, `legalAgreements`.
-
-### `DeltaResult` — Incremental Sync
-```graphql
-type DeltaResult { id: ID!, delta: DeltaEnum! }   # UPDATED | NOT_FOUND | NEW
-```
-Query fields: `pageDelta(ids:)`, `actionDelta(ids:)`, `contractorEntityDelta(ids:)`,
-`personMemberDelta(ids:)`, `templateDelta(ids:)` — all on `currentOrganization`.
-
-Pass a set of cached IDs → get back which ones changed, were deleted, or are new.
-
-### Mutation Payload Pattern
-Most mutations return: `{ item: TypeUnion, errors: ValidationErrors }` or
-`{ item: SomeType, nextTasks: [MinimalTaskInterface], errors }` (page/task mutations).
-
----
-
-## Type Inventory by Area
-
-### Pages
-| Type | Kind | Purpose |
-|------|------|---------|
-| `BasePageInterface` | INTERFACE | 50 fields shared by all pages |
-| `BasicPage` | OBJECT | Non-staged page (implements BasePageInterface) |
-| `PhasedPage` | OBJECT | Multi-stage form/register (implements BasePageInterface) |
-| `PageUnion` | UNION | `BasicPage \| PhasedPage` — returned by queries |
-| `Stage` | OBJECT | Single stage of a PhasedPage |
-| `MinimalStage` | OBJECT | `id, name, ordering, state` — lightweight |
-| `UpdatePageInput` | INPUT | `id!, stageId, submit, dataFields, task, page, patchVer, publish` |
-| `PageInput` | INPUT | `locations, otherTags, timeZone, state, taskPriority, name, externalId` |
-| `DataFieldInput` | INPUT | Union-like — one of 20 field type sub-inputs |
-| `DataFieldOneToManyInput` | INPUT | `additions, updates, deletions` for dataFields |
-| `CreateFromTemplateInput` | INPUT | `templateId!, dataFields!, page, stageId, submit, attach` |
-
-**Queries:** `org.page(id:)`, `org.pages(searchConf:, after:, first:, ...)`, `org.myDraftPages`,
-`org.allPages`, `org.templates`, `org.fullTemplates`, `org.minimalTemplates`
-
-**Key mutations:** `updatePage`, `archivePage`, `unarchivePage`,
-`createPageFromTemplate`, `buildPageFromTemplate`, `createPageDraft`,
-`deleteDraftPage`, `publishDraftPage`, `approveReviewPageTask`, `rejectReviewPageTask`
-
-**`PageUnion` members:** Only `BasicPage` and `PhasedPage`. Always query `__typename` to
-dispatch to the right Ruby model class.
-
-### Actions
-| Type | Kind | Purpose |
-|------|------|---------|
-| `Action` | OBJECT | Action instance |
-| `Category` | OBJECT | Action category (name, value, archived, weight) |
-| `UpdateActionInput` | INPUT | `id!, name!, status!, updateMode, recurrence, closeDetail, ...` |
-| `CreateActionInput` | INPUT | `name!, status!, recurrence, linkedResource, draft, ...` |
-| `ActionRecurrenceInput` | INPUT | `daily, weekly, or monthly` sub-input |
-| `SeriesUpdateMode` | ENUM | `ALL \| FORWARD \| ONE` |
-
-**Gem gaps:** `recurrence`, `updateMode`, `tags`, `dueIn/reminderIn`, `linkedResources`
-
-### ContractorEntities
-| Type | Kind | Purpose |
-|------|------|---------|
-| `ContractorEntity` | OBJECT | Contractor org |
-| `UpdateContractorEntityInput` | INPUT | Uses `IdDiffInput` for `leadContractorIds`, `associatedPeopleIds` |
-| `CreateContractorEntityInput` | INPUT | Uses `[ID!]` (flat arrays) for same fields |
-
-### Location Structures
-| Type | Kind | Purpose |
-|------|------|---------|
-| `LocationNodeInterface` | INTERFACE | Shared by all location nodes |
-| `UpdateLocationStructureInput` | INPUT | `id!, name, visitorManagementEnabled, archived, published, weight` |
-
-No `patchVer` on location structures.
-
-### Visitor Management / CheckIn
-| Type | Kind | Purpose |
-|------|------|---------|
-| `CheckInConfig` | OBJECT | Kiosk configuration — has `patchVer: Int!` |
-| `VisitorType` | OBJECT | Visitor category with check-in fields |
-| `Visit` | OBJECT | Check-in record |
-| `UpdateCheckInConfigInput` | INPUT | `id!, locationIds: IdDiffInput, visitorTypeConfigurations:, requirements:, ...` |
-
-**Key for RS location fix:** `updateCheckInConfig(input: { id:, locationIds: { additions: [...], removals: [...] } })`
-
-**Queries on org:** `checkInConfig(id:)`, `checkInConfigs(...)`, `visitorTypes(...)`,
-`visits(...)`, `visitStatus(...)`, `identifyVisitor(...)`
-
-**Mutations:** `checkIn`, `checkOut`, `checkInOnBehalf`, `checkOutOnBehalf`,
-`createCheckInConfig`, `updateCheckInConfig`, `destroyCheckInConfig`,
-`createVisitorType`, `updateVisitorType`, `destroyVisitorType`
-
-### PersonMembers
-| Type | Kind | Purpose |
-|------|------|---------|
-| `PersonMember` | OBJECT | Person (user, contractor, employee) |
-| `PersonSchema` | OBJECT | Custom person schema (org-specific person data model) |
-
-No `PersonMemberInput` — person management is not exposed as mutation (read-only in this API).
-
-**Queries:** `personMember(id:)`, `personMembers(searchConf:)`, `attachablePersonMembers(searchConf:)`,
-`personMembersCreatedSince(date:)`, `personMemberDelta(ids:)`
-
-### Registers
-| Type | Kind | Purpose |
-|------|------|---------|
-| `Register` | OBJECT | Register (page collection/module) — dashboards, templates, pages, preset views |
-| `PresetView` | OBJECT | Saved column/sort config for `previewPages`; id used as `presetViewId` argument |
-
-**Queries:** `register(id:)`, `registers`, `minimalRegisters`, `register.presetViews`
-
-**Mutations:** `createRegister`, `updateRegister`, `destroyRegister`,
-`createPresetView`, `updatePresetView`, `permissionPresetView`, `destroyPresetView`
-
-**Gem coverage:** `Builder::Register` (create/update/destroy) + `Builder::Register::PresetView`
-(list/create/update/permission/destroy). `Query::RegisterPresetViews` to list views by register.
-`Base::Register`, `Model::Register`, `Base::PresetView`, `Model::PresetView` implemented.
-
----
-
-## Enums Quick Reference
-
-| Enum | Values |
-|------|--------|
-| `StateEnum` | `INACTIVE` / `ACTIVE` / `COMPLETE` |
-| `ActionsStatusEnum` | `open` / `closed` |
-| `TaskPriorityEnum` | `low` / `medium` / `high` / `none` |
-| `SeriesUpdateMode` | `ALL` / `FORWARD` / `ONE` |
-| `DeltaEnum` | `UPDATED` / `NOT_FOUND` / `NEW` |
-| `StageStateEnum` | check schema — `active`, `completed`, `pending`, etc. |
-
----
-
-## Gem Coverage Map
-
-| Area | Queries | Mutations | Gem status |
-|------|---------|-----------|------------|
-| Actions | ✓ action, actions, actionCategories | ✓ create, update, archive | Well covered. Gaps: recurrence, updateMode, tags |
-| ContractorEntities | ✓ contractorEntities, contractorEntity | ✓ create, update, destroy, manageRelationships | Well covered. Verify IdDiff on update |
-| LocationStructures | ✓ structure, structures, locationDraftById | ✓ draft mutations | Well covered |
-| **Pages** | **✓ fully covered** | **✓ fully covered** | **Phases A–E complete 2026-06-08** |
-| PersonMembers | ✗ | n/a | Gap |
-| Registers | ✓ register, registers, presetViews | ✓ create, update, destroy + preset view CRUD | Covered 2026-06-08 |
-| VisitorManagement | ✗ | ✗ | Gap (customer urgency) |
-| Dashboards/Charts | ✗ | ✗ | Future — see TODO |
-| Delta queries | ✓ pageDelta | n/a | Done |
-| AI tools | ✗ (AiSummary/SmartFill read-only) | ✗ (mutations pending) | See TODO — AI field mutations |
-
----
-
-## Key Rules for Implementing New Areas
-
-1. **Always fetch before update.** If the output type has `patchVer`, you cannot update
-   without first querying the current value. Build this into the `from_model` input class.
-
-2. **Create vs Update input classes are different.** `IdDiffInput` in update, `[ID!]` in
-   create — always check both input types separately.
-
-3. **Spread `__typename` on union types.** `PageUnion`, `DataFieldUnion`, `SectionUnion`
-   all require `__typename` in the fragment to dispatch to the right Ruby model class.
-
-4. **Mutations always use `input:` wrapper.** No mutation has separate top-level args.
-
-5. **Check `nonNull` carefully.** `required: true` in a Ruby input class should match
-   `field: Type!` in the schema. Mismatches cause server validation errors.
-
-6. **OneToManyInput for nested array updates.** Where you see `*OneToManyInput`, that
-   area needs separate `additions`, `updates`, and `deletions` handling — not a flat replace.
-
----
-
-## Files to Check Before Implementing Anything
-
-```
-.ai-assistance/code/schema_analysis.md       ← full schema survey
-.ai-assistance/code/diff_as_input.md         ← as_update/as_input pipeline spec
-.ai-assistance/code/ecoportal_schema_reference.md  ← this file
-.ai-assistance/projects/page-model/TODO.md   ← page project plan
-.ai-assistance/projects/api-v2-to-graphql-migration/DECISIONS.md  ← core arch decisions
-lib/ecoportal/api/common/graphql/model/as_input.rb  ← current AsInput (known issue: no patchVer injection)
-lib/ecoportal/api/graphql/logic/base_query.rb       ← query dispatch (recently updated)
-lib/ecoportal/api/graphql/interface/base_page.rb    ← BasePage partial mapping
-```

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

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