ecoportal-api-graphql 1.3.9 → 1.3.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c1990322b8462a243436be2fbd9b7194512fa2ce5222a1fa5d601e248a67e4f
-  data.tar.gz: 5ed9647580308227e46a57f00fd29db20603dc66f221167630205a9fffe94ae4
+  metadata.gz: 78e2adbcdb62b6d2fdbf2ddb5906d9d8b5b93464af6269936b7eeda2dc94cb17
+  data.tar.gz: e6c55777dab78795abe7b81f419275cb52ec82a986aa92ee0da4affa4d5ca7e8
 SHA512:
-  metadata.gz: 6bd2a2fc3852bfa39f5923f0fa2a5b1a63a0fc639454b9d15ea8bbdee8276aa1a2fe7b3ddc625687a9d99e8fcb3497c7760c675390782b518a2b0a35eb9edf76
-  data.tar.gz: 01bbe1985ea4569504d703fe2ed9a93d06783e96c6e1accf9159d1e9973cf2a5cf5930c23a2d73b9eb5d79ccc00f58bd6ad6bb6ef5db7ca3686673ea5a0f0410
+  metadata.gz: 2bff88bcf06b31025a011fdb2b7d5f4a209aaa92b21c4c6c09ef1439da39a0b1e76fe75a204e5d4bc3e55dda5b7d4d6b215554650007b6d5097afa388ca08537
+  data.tar.gz: 0df6a4578b1ddbefa765f813fd97efd5f8e55fc84ad0384a7e7e6459f2ddc040dc6d8999af2493bb4e6368a638254ca7d8ed2154b7eae27bc40b965b80a94be4

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/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

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

@@ -0,0 +1,175 @@
+# Template Lifecycle, Diffing, Pairing & Deployment — Domain Knowledge
+
+**Status:** authoritative domain capture (harvestable by ep-ai-standards). Sourced from Oscar
+(platform maintainer) 2026-07-03, with schema/code facts verified inline. This is the single
+reference for the template diff/deploy/sync problem space — do not re-derive it from scratch.
+
+Related: `graphql_domain_knowledge.md` (§ genome), `.ai-assistance/projects/template-diff-deploy/`,
+`.ai-assistance/projects/template-maintenance/`, `.ai-assistance/projects/qa-services-delivery/`.
+
+---
+
+## 1. Why this matters
+
+Most quality work in Services Delivery revolves around **template changes** and the **tech-script
+fixes** applied to a register's pages after a **failed QA on a published template** produced wrong
+pages. Templates are the epicenter of admin + troubleshooting automation — **not a QA-only concern**.
+
+## 2. The UAT→PROD template lifecycle and its failure modes
+
+Jira tickets (service **xor** support) raise actions to **change templates** (most commonly). Those
+changes are either:
+- applied **directly to the PROD template** (or a DEV template that becomes PROD on the org launch date), or
+- applied first to the **UAT** site template, then replicated to PROD after customer approval.
+
+Because the whole process is **manual**, it regresses in two directions:
+- **Regression A (lost changes):** someone unpublishes/replaces the PROD template with a **YAML backup
+  copy of UAT**. Any PROD-only changes not present in UAT are **silently lost**.
+- **Regression B (premature release):** UAT already carried changes **not yet approved for release**;
+  replacing PROD with UAT **releases them**, and the customer becomes unhappy.
+
+Current mitigation (costly): hand-account **every** UAT change in detail; the **same staff member**
+who changed UAT re-does those changes in PROD. This introduces its own errors — PROD may differ from
+UAT, or the person forgets some changes. Goal: make this **smooth, effective, efficient** — no extra
+comms, no back-and-forth, no trust loss, no rectifying tech-scripts.
+
+## 3. The core obstacle — no stable identity (MongoDB)
+
+MongoDB assigns a **distinct ID to every object in the nested page hierarchy**, and IDs are **not
+shared** across: template vs its child pages, page vs page, UAT template vs PROD template. Nothing
+has the same ID as its counterpart anywhere.
+
+Consequences seen platform-wide:
+- Customer integrations must **fetch the page model first** just to learn sub-object IDs (e.g.
+  `dataField` ids) before building a patch payload.
+- The **field ref** (a truncated sha of the label name) is used as a pseudo-key in analytics — it's
+  unstable; the **Field ID project** exists to add certainty here.
+
+## 4. THE key distinction — self-version diff vs cross-object diff
+
+| | IDs | Pairing needed? | Difficulty |
+|---|---|---|---|
+| **Self-version** (same object, vN vs vN+1) | **retained** | none — match by id | trivial ✅ **built** |
+| **Cross-object** (UAT↔PROD, page↔template) | **different** | yes — equivalence | hard |
+
+- **Self-version** captures "what did this ticket change to the UAT template" exactly, as long as the
+  original snapshot was retained. Implemented: `Ecoportal::API::GraphQL::Diff::VersionDiff` (gem).
+- **Cross-object** is the hard one: to diff, you must **pair counterpart objects** across two id-spaces,
+  translate to a common id-space in memory, diff, then map back. Only a fully-mapped copy can be diffed.
+
+## 5. The genome signature — VERIFIED facts + why it can't be the sole key
+
+**What it is:** an identifier introduced by the original ecoPortal developer (~2015/16) intended to
+pair objects across a template and its child pages, and across YAML backup→restore. The genome is
+**inherited** template-(sub)object → child-page-(sub)object, and copied on restore. It **grows** each
+time it is restored or a child page is created (a related backend commit had to be amended for this).
+
+**⚠️ VERIFIED 2026-07-03 (corrects the older "not exposed" claim in `graphql_domain_knowledge.md`):**
+The live NewEp GraphQL schema (`.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json`)
+**DOES expose `genomeSignature: String`** on the **`DataFieldsInterface`** and on **every concrete
+data-field type** (PlainText, RichText, Date, Number, Gauge, People, Select, Checklist, TagField, Geo,
+Signature, ContractorEntities, CrossReference, ImageGallery, File, Mailbox, ActionsList, Law,
+AiSummary, TableField, Chart, FrequencyRateChart, EmbeddedStructure, PageAction). APIv2 also exposed it
+(developer "Rien" eventually exposed everything). It is **on data fields, not on sections/stages/pages**
+(per the introspection). **Our gem does NOT yet request it** — no fragment/model field — so to use it
+we add `genomeSignature` to the data-field fragment + `Base::Page::DataField`. It is **not indexed** in
+Elasticsearch.
+
+**Why genome is NOT an unarguable pairing key (Oscar's failure modes — design constraints):**
+- (a) pairing was **manual**, with no platform support;
+- (b) **new features** (new field types, linked-field configs, …) were never added to the genome solution;
+- (c) it's **wrong for select options** — an option's key is the **value (primary)** or **name
+  (auxiliary)**, never the genome;
+- (d) it wrongly **syncs checklist fields** from the template (shouldn't happen);
+- (e) the premise "genome is always an unarguable pairing key" is **false**: a configurator may
+  **re-use** a field for something else then add a same-name/type field (realising the mistake); a
+  structural/conceptual **revamp** may carry same-label/type fields re-used for a different purpose; or
+  a field is **re-purposed** keeping its genome (e.g. `Date logged:` → `Date of sign-off:`);
+- (f) **data-loss accounting** is incomplete and under-documented.
+
+The abandoned backend solution built on genome: `app/services/migration/*`, notably
+`Migration::GenomeKindship` — synced children pages to their parent template via genome pairing.
+Abandoned for the reasons above, but its **founding principle is valid** (see §6).
+
+## 6. The load-bearing simplifying principle (valid)
+
+**Sections/stages are scaffolding, NOT data containers.** Customer data lives in the **data-fields**
+(+ core page properties: old tags → now `location_ids` + `custom_tags`, `created_at`, …). Therefore
+**restructuring is tractable as long as you can pair the customer data between the original-stage
+field and the end-state field.** This dramatically shrinks the problem: **pair fields precisely; treat
+structure as context.** That `genomeSignature` lives on data-fields aligns exactly with this.
+
+Proven in practice by the migration-scripts framework (`doc/scripts/v*`): field-pairing via `FIELDS_MAP`
+(`20231129_stolt_tra_migrate.rb`, `20240125_gns_con_migrate.rb`); later, due to page variability in
+some registers, a different approach — **re-import via the current template's import spreadsheet**
+(customer fills a data CSV extract) + a final tech-script for non-importable fields
+(`20251202_luna_park_migration.rb`, `20260615_resene_copy_files.rb`).
+
+## 7. Pairing = equivalence matching (the reframe — CONFIRMED by Oscar 2026-07-03)
+
+Stable identity across independent Mongo objects does not exist, so **reframe from identity to
+EQUIVALENCE** — a **record-linkage / entity-resolution** problem:
+
+- Combine **multiple weak signals** into a **confidence score**:
+  `genomeSignature` (strong, now available on data fields), **type + label** (already implemented:
+  eco-helpers `HelpersMigration::TypedFieldsPairing` / `copying.rb`), **section heading + position**,
+  **select options-by-value**, structural context.
+- **Auto-accept** high confidence; **route ambiguous / low-confidence to a HUMAN**; the assistant asks
+  the user to resolve unmatched cases and adjudicate doubtful pairings.
+- **Persist every decision to a LEARNING LEDGER** (confirmed a first-class artifact): the pairings +
+  the log of *how* each was resolved, for future reuse. Over time most cases auto-resolve; the tool
+  asks only about genuine novelty. The accumulated ledger also **feeds Product's Field-ID /
+  template-entity-id** effort (we are the interim bridge that generates their data).
+
+## 8. Diff MODALITIES — multiple diff forms for different processes (Oscar 2026-07-03)
+
+There is **no single diff**. Different processes need different modes. Fields may **move between
+sections**, or **must go to a specific section** — some processes care about section membership,
+others only about the field's data pairing. The engine is a **family of strategies** over configurable
+axes:
+
+- **Pairing strategy:** by-id (self-version) · genome · type+label · assisted/ledger (cross-object).
+- **Comparison scope:** structural (stages/sections/fields) · config-only (field configuration,
+  options, forces) · data-migration (field→field data pairing, structure-agnostic).
+- **Move sensitivity:** section-move-aware vs section-agnostic; ordering-sensitive vs -insensitive.
+- **Direction/intent:** changelog (what changed, for a ticket) · deployment delta (UAT→PROD replay) ·
+  sync-readiness (can this register/subset be synced to the active template?).
+
+`Diff::VersionDiff` implements the **self-version, id-paired, structural, section-move-aware** mode.
+The others compose the same `Change` output with a different pairing front-end and comparison scope.
+
+## 9. Layering — where each capability lives (CONFIRMED)
+
+| Layer | Owns | Consumers |
+|---|---|---|
+| **ecoportal-api-graphql** (gem) | *mechanics*: read model, WorkflowCommand vocab, build (emitter) + **diff (VersionDiff)** + apply; `genomeSignature` fragment (to add) | everyone |
+| **eco-helpers** | *orchestration*: pairing engine (human-in-loop), learning ledger, samples, session flows, `TypedFieldsPairing` | tools, scripts |
+| **ecoportal-qa** | QA-facing surface (checks/reporters/Jira/CLI); **should use the gem's model, not re-implement it** | QA team |
+| admin / troubleshooting / integrations | consume gem + eco-helpers directly | — |
+
+## 10. The pipeline (how the pieces compose)
+
+```
+pair (id | genome | type+label | assisted+ledger)
+     └─► diff on paired model (mode-specific)
+             └─► delta as WorkflowCommands (the emitter)
+                     └─► apply to target ─► verify (ecoportal-qa) ─► monitor (register sync-ready tickboxes)
+```
+The **self-version changelog** is a portable "commit": a `Change` set that, once id-translated through
+a pairing map, **replays onto PROD**.
+
+## 11. Product context
+
+Register-template-sync is **not yet scoped** by Product (Field-ID takes precedence). Product is working
+out a **template-entity-id** to differentiate template versions within a register (to pair pages made
+from a previous template version with the current one) + **customer filters by template**. Our tools
+are the interim bridge and **generate the pairing data** Product needs.
+
+## 12. Status & next steps
+
+- ✅ **Done:** `Diff::VersionDiff` (self-version, exact, id-paired) — gem, 8 specs.
+- **Next:** (1) add `genomeSignature` to the data-field fragment + `Base::Page::DataField`; (2) synthesise
+  WorkflowCommands from a `Change` set (delta → commands); (3) the **pairing engine** (equivalence,
+  multi-signal, human-assisted, ledger) in eco-helpers; (4) **diff modalities** as strategies;
+  (5) cross-template deploy (UAT→PROD replay); (6) monitoring / sync-readiness; (7) tighten `ecoportal-qa`
+  to use the gem's page-model instead of its own `TemplateModel`.

data/.ai-assistance/code/workflow-command-guide.md

@@ -436,3 +436,31 @@ payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
 raise "Commands failed: #{payload.body.inspect}" unless payload.success?
 puts "Applied #{cmds.size} commands. New patchVer: #{payload.patchVer}"
 ```
+
+---
+
+## Schema realities — input-key gotchas (verified 2026-07-04 against the live introspection dump)
+
+These are the ways the command bus does **not** behave the way you'd expect. Verifying against the
+schema dump (`.ai-assistance/tmp/*_live_ep_graphql_schema.graphql.json`) before assuming a key exists
+saves a live round trip.
+
+- **`addField` (`WorkflowAddFieldInput`) keys = EXACTLY** `placeholderId, fieldType, label, stageId`
+  (NON_NULL), `sectionId` (NON_NULL), `column`. It does **not** accept `description` or `required`.
+- **A field's `description` is set via `editFieldConfiguration`** (`WorkflowEditFieldConfigurationInput`
+  has a top-level `description: String`), NOT via `addField`. To build a field *with* a description
+  (e.g. a CSV / hidden-field **identity token**), emit `addField` then a follow-up
+  `editFieldConfiguration(dataFieldId: <field>, description:)`. This is the seam `Diff::CommandSynthesizer`
+  and `Builder::TemplateBuilder` use (via `placeholderId`/`ref` when the field is created in the same batch).
+- **`required` cannot be set through the command bus at all.** There is **no `required` input key
+  anywhere** — not on `WorkflowAddFieldInput`, not on `WorkflowEditFieldConfigurationInput` (top-level),
+  not on any of its **12 `byType` sub-inputs**. Treat field-`required` as **read-only / out-of-band**:
+  read it from the template, don't try to mutate it. (ecoportal-qa `:skip`s `required`-readiness for
+  this reason; `VersionDiff`'s `BYTYPE_CONFIG` omits it.)
+- **Structural back-refs:** an added field's `addField` carries its parent `sectionId` + `stageId`;
+  an added **section** has no stage-id key, so wire it with a follow-up
+  `addStageSection(stageId:, sectionId:)`. `Diff::CommandSynthesizer` threads all of these via
+  `placeholderId`/`ref()` (parent placeholder when same-batch, else real id; omitted when unknown).
+
+**Rule of thumb:** before adding a key to a `WorkflowCommand` builder, confirm it exists on that input
+type in the schema dump. Absent keys are silently dropped (or rejected) — they do not error informatively.

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

@@ -2,6 +2,27 @@
 
 ## Pending
 
+- [ ] **⏰ CI: query-validation step (DUE by 2026-07-17 — within 2 weeks of 2026-07-03)** — wire
+  `tests/validate_queries.rb` into CI so the whole class of GraphQL selection bugs fails *before*
+  release, not in a client runner. **Use a FRESHLY-introspected schema** (do NOT commit the 6.3MB
+  dump — it goes stale); fail the build only on the two structural classes ("field must have
+  selections" / "selections can't be made on scalars"). Motivated by the 2026-07-03 v1.3.10 hotfix
+  (LocationStructure `updatedAt`/`createdAt`) — those queries had no spec and first broke in prod.
+  Also: fix the 3 flagged union findings — **TRIAGED 2026-07-03: all THREE are REAL bugs** (verified
+  by rendering the assembled docs + re-validating fixes; not harness/dump artifacts). Each selects
+  fields directly on a union (invalid GraphQL) — wrap in the members' shared interface:
+    - `Query::PageWithForces` (page_with_forces.rb:33-35): bare `forces` on `PageUnion` →
+      `... on BasePageInterface { forces { ...ForceFields } }`. ALSO `fragment ForceFields`
+      (fragment/force.rb:15,20) selects `id` on `DataFieldBinding`/`SectionBinding` which have NO `id`
+      (only name/reference/referenceId) → drop `id` (or use `referenceId`).
+    - `Query::PagesWorkflowCommands` (pages_workflow_commands.rb:33-37): bare `workflow` on `PageUnion`
+      → `... on BasePageInterface { workflow { ... } }`. (The "unused variable" errors were an
+      artifact — a validator cascade from the union error; no action on the vars.)
+    - `Query::RegisterPresetViews` (register_preset_views.rb:71): bare `{id key name weight}` on
+      `FieldConfigurationUnion` → `... on FieldConfigurationInterface { id key name weight }`.
+  None of these 3 queries have specs — add render/validation specs alongside the fixes. These are
+  latent (not the users-sync incident); PageWithForces is WIP. Ship as a follow-up patch (1.3.11).
+
 - [x] **Builder::Register** — `createRegister`, `updateRegister`, `destroyRegister` mutations.
   `Base::Register`, `Model::Register`, `Input::Register::Create/Update`, `Payload::Register`.
   `Builder::Register` with `create`, `update`, `destroy`, and `preset_view` sub-builder.