ecoportal-api-graphql 1.3.10 → 1.3.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 180d0e0ea70c7fb3462ae6bdec6ef78d1480c97be0861bec6e3e4bbb4abba751
-  data.tar.gz: e2733075993edee570ef5762fe06cdaac035609e313f583b43753a4da21f0fd3
+  metadata.gz: 74b442ca224440bee94f3f88522a4233b995d187db1b70ba31a0801e0691d3eb
+  data.tar.gz: 5d5d05fdf46fac5a32a12c5d4c8e47c21b913332bbe04c40a3ab81beeacbab9a
 SHA512:
-  metadata.gz: e05ae227d2cc97f91c250b74c6e831cbec0f9c9f8822d0bfdebacccfbe519cf229a48f2b9222623faf1c1ff2622ac2e7c1538e0036fa4494cb7a3e9082ba6f51
-  data.tar.gz: ed6a82e38512fee2375a0bd880c1c721cee1d28597055cbeda9117a454d59f7d0a6b8bfdb1cb43fbe66fa18860a7508f426fb982ac0035d01b26140e789b1ecd
+  metadata.gz: 7d667e7ed09fc6ed6fd200695567eb25a8bb5f4f41b3b98882e04d84acd1775c1a17dc7d424e82f26b7f89d4f826bb46c25fddc0ef5fc526e8731aaccd73193b
+  data.tar.gz: 324b54e96de9f7ae82e71bf1b2c0427fa6fd4ed99d0153ec836a85cf68d76d5ce8f8462865b29cddd446015caa2b4a5fcaf940c5c2866970d7814a2d0495a73b

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

@@ -0,0 +1,243 @@
+# Diff — Command Synthesis, Deploy & Pairing Engine
+
+**Area:** `lib/ecoportal/api/graphql/diff/` · **Status:** built (gem branch
+`feature/template-diff-deploy-pairing`) · **Domain reference (read first):**
+`template_diff_pairing_domain.md`.
+
+This doc covers the diff → command → deploy pipeline and the cross-object pairing engine + learning
+ledger. `VersionDiff`/`Change` (the self-version structural diff) are covered inline in their files.
+
+---
+
+## 1. The pipeline
+
+```
+pair (id | genome | type+label | ledger)          Diff::Pairing::Engine (+ Ledger)
+     └─► diff on paired model                       Diff::VersionDiff  → [Change]
+             └─► delta as WorkflowCommands           Diff::CommandSynthesizer (+ IdResolver)
+                     └─► apply (gated on unsupported) Diff::Deploy#execute!
+```
+
+Self-version (same object, retained ids) needs NO pairing — `VersionDiff` matches by id and the
+synthesiser replays as-is. Cross-object (UAT↔PROD) needs pairing to translate the ids first.
+
+---
+
+## 2. Classes
+
+| Class | File | Role |
+|---|---|---|
+| `Diff::Strategy` | `diff/strategy.rb` | Composable diff config (pairing × scope × move-sensitivity × intent); `#filter(changes)` |
+| `Diff::VersionDiff` | `diff/version_diff.rb` | Self-version (`:id` pairing) front-end → `[Change]`; accepts `strategy:` |
+| `Diff::CrossObjectDiff` | `diff/cross_object_diff.rb` | Cross-object front-end: pairs fields via `Pairing::Engine`, emits same `[Change]` |
+| `Diff::Change` | `diff/change.rb` | One change (op/kind/id/before/after/parent_id) (unchanged) |
+| `Diff::CommandSynthesizer` | `diff/command_synthesizer.rb` | `[Change]` → ordered built `WorkflowCommand` batch + `unsupported` |
+| `Diff::IdResolver` | `diff/id_resolver.rb` | Maps `resolve(kind, human-key) => id` (stage name / section heading → target id) |
+| `Diff::Deploy` | `diff/deploy.rb` | Orchestrates diff → commands → apply; gates on `unsupported` |
+| `Diff::Pairing::Signals` | `diff/pairing/signals.rb` | Weak signals (genome/type/label/options), each 0.0..1.0 or nil |
+| `Diff::Pairing::Candidate` | `diff/pairing/candidate.rb` | Scored source↔target proposal (`score`, `signals`, `matched_by`) |
+| `Diff::Pairing::Engine` | `diff/pairing/engine.rb` | Multi-signal equivalence matcher → accepted / ambiguous / unmatched |
+| `Diff::Pairing::Ledger` | `diff/pairing/ledger.rb` | Persisted confirmed equivalences (JSON); consulted first |
+
+---
+
+## 3. CommandSynthesizer — edit mode
+
+`CommandSynthesizer.new(changes, resolver: nil)`. Emits in a dependency-safe order (stages → sections
+→ fields → options; within a kind removes → adds → moves → edits). A `command_for` result may be a
+single hash, an **Array** of hashes (a move that emits remove+add), or nil (unsupported); `build_all`
+normalises via `wrap` (NOT `Kernel#Array`, which would splat a Hash).
+
+| Change | Command(s) | Notes |
+|---|---|---|
+| stage added/removed/moved | `addStage`/`removeStage`/`moveStage` | |
+| stage `name` changed | `editStage(stageId, name)` | |
+| section added/removed | `addSection`/`removeSection` | |
+| section `heading` changed | `editSectionHeader(sectionId, header)` | |
+| **section `stage` moved** | `removeStageSection` + `addStageSection` | **needs resolver** for stage ids; else UNSUPPORTED |
+| field added/removed | `addField`/`removeField` | |
+| field `label` changed | `editFieldConfiguration(dataFieldId, label)` | |
+| **field `section` moved** | `moveField(id, sectionId)` | **needs resolver** for section id; else UNSUPPORTED |
+| field `type` changed | — | **UNSUPPORTED** (no `editFieldType`; a rebuild would drop data) |
+| option added/removed/changed(label,weight) | `add/remove/editSelectFieldOption` | uses `change.parent_id` (field id); nil → UNSUPPORTED |
+| **field_config changed** (typed byType) | `editFieldConfiguration(byType: { <key> => { <attr> => after } })` | `change.by_type` names the sub-hash (`:gauge`/`:select`/`:date`); nil by_type → UNSUPPORTED. Emitted only for confirmed read↔write-key matches (see VersionDiff) |
+| **gauge_stop added** | `addGaugeFieldStop(dataFieldId, threshold, color)` | threshold+color carried on `change.after`; `parent_id` = gauge field id |
+| **gauge_stop removed** | `removeGaugeFieldStop(dataFieldId, stopId)` | `parent_id` = gauge field id |
+| **gauge_stop changed** (threshold\|color) | `editGaugeFieldStop(dataFieldId, stopId, <attr>)` | one command per changed attr |
+
+**Resolver contract:** any object answering `resolve(kind, key) => id | nil`. Without one, moves stay
+UNSUPPORTED — the synthesiser NEVER guesses a target id. `IdResolver.from_doc(target_doc)` builds one
+by indexing stage names + section headings; **ambiguous keys (duplicates) resolve to nil** (safe).
+
+---
+
+## 4. Deploy
+
+```ruby
+plan = Diff::Deploy.from_versions(before_doc, after_doc)                    # self-version replay
+plan = Diff::Deploy.from_versions(uat_v1, uat_v2, target_doc: prod_doc)     # cross-object: moves resolve vs PROD
+plan.commands        # ordered built command hashes, ready for executeWorkflowCommands
+plan.unsupported     # [Change] needing human handling (never guessed)
+plan.changelog       # human one-liners
+plan.execute!(page)  # sends via page.execute_workflow_commands; RAISES if unsupported unless allow_partial: true
+```
+
+Inert until `execute!` with an explicit executor. `from_versions` derives an `IdResolver` from
+`target_doc:` (override with `resolver:`).
+
+---
+
+## 5. Pairing engine (equivalence matching)
+
+Cross-object pairing is entity-resolution, not lookup (no shared Mongo ids). `Engine#pair(sources,
+targets)` returns `Result(accepted, ambiguous, unmatched)`:
+
+1. **Ledger first** — a previously-confirmed pair auto-resolves (`matched_by: :ledger`, score 1.0),
+   consuming the target so it can't be re-assigned. Pairing improves over time.
+2. **Score the rest** — every remaining source×target via `Signals`, weighted mean over the signals
+   that APPLY (nil signals excluded so a select field isn't penalised for absent genome).
+3. **Greedy one-to-one assignment**, strongest links first.
+4. **Classify:** `accepted` (score ≥ `accept_threshold` 0.85 AND not within `tie_margin` 0.1 of the
+   runner-up) · `ambiguous` (0.5–0.85, or a near-tie) · `unmatched` (< 0.5 review_threshold).
+
+**Signals + weights:** genome 0.5, type 0.2, label 0.2, options 0.1.
+- **genome** — match 1.0, mismatch 0.0 (does NOT veto — a field may be re-purposed keeping its
+  genome, or genome may be absent on newer types), nil when neither side carries one. Strong but
+  **fallible** (6 documented failure modes — see domain ref §5).
+- **type** — `__typename` equality (a type change disqualifies a data pairing).
+- **label** — case/space-insensitive exact = 1.0, else token Jaccard (partial credit for a re-purpose
+  candidate like `Date logged` → `Date of sign-off`).
+- **options** — select options overlap by **value** (primary) / label — the correct option identity,
+  never genome; nil for non-select fields.
+
+**Never guesses:** only `accepted` is safe to auto-apply/record; `ambiguous`+`unmatched` are surfaced
+for a human. A same-label/type field whose genome CONTRADICTS is pulled below accept (→ ambiguous or
+unmatched), never auto-paired.
+
+---
+
+## 6. Learning ledger (first-class artifact)
+
+`Ledger` records only CONFIRMED equivalences (auto-accepted high-confidence or human-adjudicated),
+keyed by `(kind, source_id)`, storing `target_id` + `matched_by` + `confidence` + `signals` +
+`recorded_at`. `Engine#confirm!(candidate, matched_by: :human)` writes back. JSON round-trips via
+`Ledger.load(path)` / `#save`; a missing file yields an empty writable ledger; a later record
+supersedes an earlier one (human corrects an auto-accept). The how-resolved log is the interim bridge
+data Product's Field-ID / template-entity-id effort needs.
+
+> Note the struct member is `matched_by`, NOT `method` — `method` would shadow `Object#method`
+> (`Lint/StructNewOverride`). The `Ledger#record` / `Engine#confirm!` keyword is likewise `matched_by:`.
+
+---
+
+## 7. Gauge stops + typed byType config emission (round #3 — DONE)
+
+`VersionDiff` now emits two new `Change` kinds (id-paired, self-version):
+
+- **`:gauge_stop`** — diffs each Gauge field's `stops` list (`{ id, threshold, color }`, matched by
+  retained stop id): added (carries `after: { threshold:, color: }`), removed, changed
+  (`threshold`/`color`). `parent_id` = the gauge field id.
+- **`:field_config`** — typed per-field configuration changes, `parent_id` = field id and `by_type`
+  = the `editFieldConfiguration.byType` sub-hash key. Emission is **data-driven + conservative**
+  (`VersionDiff::BYTYPE_CONFIG`): only where the READ doc property name matches the WRITE byType
+  input key EXACTLY. Currently confirmed against the schema + input classes:
+  - `Gauge` → `{ gauge: [max] }`
+  - `Select` → `{ select: [dataType, multiple, flat, other, otherDesc] }`
+  - `Date` → `{ date: [showTime, pastOnly, todayButton] }`
+  Anything else (e.g. PlainText `multiline` — not a `plainText` byType key; `required` — no
+  editFieldConfiguration key at all) is **not emitted** (unmappable → never fabricated).
+
+`Stop` shape and the gauge byType `max` verified against
+`.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json` (`Stop { id, threshold: Float,
+color: String }`; `WorkflowEditFieldConfigurationGaugeInput { max: Float }`).
+
+## 7b. placeholderId threading (dependent intra-batch creates — round #3 — DONE)
+
+`CommandSynthesizer.new(changes, thread_placeholders:)` (Deploy passes `true` by default). When on,
+every ADDED structural node (stage/section/field) is assigned a deterministic client-chosen
+`placeholderId` keyed by its source id; `addStage`/`addSection`/`addField` emit that placeholder, and
+any later command in the SAME batch that references such a node (`addSelectFieldOption` /
+`add/edit/removeGaugeFieldStop` / `editFieldConfiguration` dataFieldId) is rewritten to the
+placeholder instead of the target-invalid source id (`ref(id)` helper). References to pre-existing
+nodes keep their real id. Threading OFF → empty map → the source ids pass through unchanged (the
+prior self-version behaviour). This makes add-then-reference sequences self-consistent within one
+`executeWorkflowCommands` call. The placeholderId inputs are native to the command modules
+(`addStage`/`addSection`/`addField` all list `placeholderId` in VALID_KEYS; `addGaugeFieldStop`
+accepts an optional one too).
+
+**Note on self-version scope:** a self-version `VersionDiff` subsumes a NEW field's options/config
+into its single `added`-field change (children are not separately emitted when the parent is brand
+new), so the natural self-version batch has no add-then-reference pair. Threading is therefore
+latent for pure self-version replay and load-bearing for the CROSS-OBJECT / assembled change-set
+replay (a field created in the batch referenced by later commands). Deploy is proven end-to-end
+against such an assembled change-set.
+
+## 7c. What remains UNSUPPORTED / deferred
+
+- **Field type change** — no schema command; would need remove+add (drops data) → always UNSUPPORTED.
+- **Moves without a resolver** — field/section moves need a target id; nil resolver → UNSUPPORTED.
+- **Non-confirmed byType config props** — anything outside `BYTYPE_CONFIG` (PlainText `multiline`,
+  `required`, RichText `markdown`/`content`, People/Table/CrossReference/etc. bodies): the read
+  fragment and/or the byType input keys were not confirmed to line up 1:1, so they are NOT emitted
+  (never fabricated). Extend `BYTYPE_CONFIG` per type once the read shape is confirmed.
+- **Gauge stop reordering** — stops are matched by id (add/remove/attr change) but a pure reorder is
+  not modelled (no ordering field surfaced on `Stop`); left UNSUPPORTED.
+- **Structural cross-references in emitted adds** — `addField`/`addSection` still emit only
+  label/placeholder (not `stageId`/`sectionId` back-refs to their added parent). Once those refs are
+  emitted, placeholder threading will thread them too (the primitive is already in place).
+- **Interactive assisted-resolution UX + `TypedFieldsPairing` as an extra signal** — eco-helpers layer.
+
+## 8. Diff modalities — `Strategy` + `CrossObjectDiff` (Phase 4 — DONE)
+
+Diffing is a COMPOSABLE FAMILY (domain ref §8), not one diff. `Diff::Strategy` is the value object
+over four axes:
+
+- **pairing** `:id` (self-version, default) · `:genome` · `:type_label` · `:assisted` (full engine).
+  `:id` needs no pairing map; the other three are `cross_object?` (need one).
+- **scope** `:structural` (all) · `:config_only` (field_config/option/gauge_stop) · `:data_migration`
+  (field changes only).
+- **move_sensitive** — false suppresses `:moved` changes; config_only/data_migration never emit moves.
+- **intent** `:changelog` · `:deploy` · `:sync_readiness` (documentation; `:deploy` keeps threading on).
+
+`Strategy#filter(changes)` applies scope + move-sensitivity to a computed change-set. `Strategy.default`
+is `{id, structural, move-aware, changelog}` — EXACTLY the pre-Phase-4 `VersionDiff` behaviour (BC).
+
+`VersionDiff.new(before, after, strategy:)` is the `:id` front-end: it computes the full id-paired
+change-set once (`all_changes`) and returns `strategy.filter(all_changes)`. Default = unchanged.
+
+`CrossObjectDiff.new(source, target, engine:, strategy:)` is the cross-object front-end for two docs
+with NO shared ids:
+1. flatten each doc's data-fields; `engine.pair(source_fields, target_fields)` (genome+type+label+
+   options, ledger-first);
+2. for each ACCEPTED pair emit `:changed(label|type)` keyed by the **source** id; target-only field →
+   `:added`; a source with no accepted target AND not in the review set → `:removed`;
+3. **never guesses** — ambiguous + unmatched sources/targets are held in `#unresolved` (surfaced for a
+   human), NOT auto-paired / auto-added / auto-removed. A same-genome RELABEL is ambiguous by design
+   (could be a re-purpose) → not auto-emitted unless the ledger/human confirms the pair.
+
+The emitted `[Change]` feeds the EXISTING `CommandSynthesizer` / `Deploy` unchanged (one emission
+layer). `Deploy.from_cross_object(source, target, engine:, strategy:)` + `Deploy#pairing` expose the
+accepted/ambiguous/unmatched for adjudication before apply.
+
+## 9. Unified BUILD emitter — `Builder::TemplateBuilder` (shares the emission layer)
+
+`lib/ecoportal/api/graphql/builder/template_builder.rb`. Turns a declarative template spec
+(stages→sections→fields→options→config→gauge-stops) into an ordered `WorkflowCommand` batch for
+`Builder::Template#create/update(commands:)`. Order: addStage → addSection → addStageSection →
+editSectionHeader → addField → addSelectFieldOption / addGaugeFieldStop / editFieldConfiguration(byType:).
+
+It uses the SAME `placeholderId` id-threading primitive as `CommandSynthesizer`: every created node
+gets a deterministic client-chosen `placeholderId` and later same-batch commands reference it (stage
+placeholder ← addStageSection.stageId + addField.stageId; section placeholder ← addStageSection.sectionId
++ addField.sectionId; field placeholder ← option/stop/config dataFieldId). So BUILD (add everything)
+and DIFF-DEPLOY (add/remove/edit the delta) emit through ONE layer. Only VALID command-input keys are
+emitted (input classes slice + compact); config is passed through under its byType sub-hash exactly as
+supplied — nothing is fabricated. UNSUPPORTED in a build spec (deferred): forces/strategies/callbacks/
+tasks/recipients (shape unconfirmed); `field_type` enum not schema-validated (passed through as given).
+
+## 10. Related
+
+- `template_diff_pairing_domain.md` — the full problem space (READ FIRST).
+- `lib/.../input/workflow_command.rb` — the command vocabulary both emitters target.
+- `.ai-assistance/projects/template-automatic-build-maintenance/{INTENT,TODO}.md` (the merged plan;
+  `template-diff-deploy/` + `template-maintenance/` are now pointers).

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

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

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

@@ -89,16 +89,26 @@ this field in template Y", even after the page was created, cloned, or restored.
 had a full solution using the genome to pair fields during template changes and page
 restorations (backup to YAML + restore).
 
-**Current state:**
-- Mostly **unused** — the Migrator solution was abandoned due to maintenance cost and
-  low usage
-- **Not indexed** — the genome is not sent to Elasticsearch
-- **Unpaired on many pages** — tech scripts that added fields without copying from the
-  template introduced fields with random creation-time genome signatures, breaking the
-  pairing with the template
-- **NewEp port status:** Uncertain — unclear whether the NewEp namespace fully ported
-  the Genome functionality from the Enzyme namespace
-- The genome is NOT currently exploitable for scripting or integration purposes
+**Current state (CORRECTED 2026-07-03 against the live schema — supersedes earlier claims):**
+- ✅ **IT IS EXPOSED IN GraphQL.** The live NewEp schema exposes **`genomeSignature: String`** on the
+  **`DataFieldsInterface`** and on **every concrete data-field type** (PlainText, Select, CrossReference,
+  People, Date, Number, Gauge, Checklist, TagField, Geo, Signature, ContractorEntities, ImageGallery,
+  File, Mailbox, ActionsList, Law, RichText, AiSummary, TableField, Chart, FrequencyRateChart,
+  EmbeddedStructure, PageAction). Verified in `.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json`.
+  APIv2 also exposed it. **This corrects the previous "NOT currently exploitable" claim, which was wrong.**
+- It is on **data fields only** (per the introspection) — not on sections/stages/pages.
+- **Our gem does not yet REQUEST it** — no fragment/model field. To use it: add `genomeSignature` to the
+  data-field fragment + `Base::Page::DataField`. (This is the real gap, not schema availability.)
+- **Not indexed** — the genome is not sent to Elasticsearch.
+- **Unreliable as a sole key** — see the failure modes (field re-use/re-purpose/revamp keep the same
+  genome for a different meaning; wrong for select options; etc.). Treat as a **strong-but-fallible
+  signal** in equivalence matching, never an unarguable key.
+- The Migrator solution (`app/services/migration/*`, `Migration::GenomeKindship`) was abandoned for
+  maintenance/coverage reasons, but its founding principle (data lives in data-fields) is valid.
+
+**Full treatment:** see `.ai-assistance/code/template_diff_pairing_domain.md` — the authoritative
+capture of the template diff/pairing/deploy problem space (lifecycle, failure modes, equivalence
+reframe, diff modalities, layering, pipeline, Product context).
 
 **Why it matters for the future:** The genome was the intended foundation for:
 - Automatically applying template changes to existing pages