ecoportal-api-graphql 1.3.13 → 1.3.16

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

@@ -1,73 +0,0 @@
-# Spec Coverage Map
-
-*Last updated: 2026-06-07*
-
----
-
-## Areas WITH specs (117 examples total)
-
-| Spec file | What it covers |
-|---|---|
-| `common/graphql/model/as_input_spec.rb` | `AsInput#as_input`, `Logic::Input.from_model`, `ContractorEntity::Update.from_model` |
-| `common/graphql/model/diff_service_spec.rb` | `DiffService#diff` — no-change, single prop, nested, root! exclusion |
-| `base/page/data_field_spec.rb` | `DataField.from_doc` dispatch, dirty tracking, `as_input` for PlainText/RichText/Select/People/Checklist, `Collection` get_by_type/get_by_name/dirty_inputs |
-| `concerns/fragment_definitions_spec.rb` | `FragmentDefinitions.assemble`, `register_namespace` cross-namespace discovery, `Fragment::Pages` integration |
-| `input/page/update_spec.rb` | `Input::Page::Update.from_model` — no-change nil, patchVer injection, publish flag, clientMutationId |
-| `input/search_conf_spec.rb` | `SearchConf` builder — all filter types, sort, query, `#with` parametrization, `as_json` |
-| `logic/assemble_fragments_spec.rb` | `BaseQuery#assemble_fragments` — single, recursive (PageFields→LocationNode), cycle safety, deduplication |
-| `model/page_union_spec.rb` | `Model::PageUnion.new` — `__typename` dispatch to Basic/Phased/fallback, opts forwarded |
-| `api_spec.rb` | Version constant smoke test |
-
----
-
-## Areas WITHOUT specs (by design or deferred)
-
-### Query / Mutation / Payload / Builder classes
-No unit specs. These classes primarily wire DSL blocks to HTTP + response wrapping —
-meaningful tests require a live or stubbed GraphQL server. Integration testing via
-`tests/` scripts (manual) is the current approach.
-
-Includes: `Query::Page`, `Query::Pages`, `Query::Templates`, `Query::RegisterPreviewPages`,
-`Query::PageDelta`, all `Mutation::Page::*`, all `Payload::Page::*`, `Builder::Page`.
-
-**Gap severity: Low** — the classes are thin wrappers; bugs show up on integration.
-If stubs become practical, priority order: `Query::Page`, `Query::Pages`.
-
-### Compat layer
-No unit specs for `Compat::Pages`, `Compat::Registers`, `Compat::StageCollection`,
-`Compat::SearchResults`. These require either a live GraphQL connection or deep mocking.
-
-**Gap severity: Medium** — integration testing with the end-script repo (pending access)
-will cover this.
-
-### Model classes (stubs and pass-through)
-`Base::Page::Basic`, `Base::Page::Phased`, `Model::Page::Basic`, `Model::Page::Phased`,
-`Base::PreviewPage`, `Base::DeltaResult`, `Base::Page::DataField::TagField/Geo/Gauge/Date/Number`
-— these are mostly DSL declarations with no business logic. Not worth unit-testing.
-
-### Fragment definitions (GRAPHQL strings)
-`Fragment::PageFields`, `BasicPageFields`, `PhasedPageFields` — assembly is tested via
-`assemble_fragments_spec.rb`. Individual fragment content is validated in integration.
-
-### Input stubs
-`Input::DeltaInput`, `Input::Page::Archive`, `Input::Page::Unarchive`,
-`Input::Page::BuildFromTemplate`, `Input::Page::CreateFromTemplate` — simple passthrough
-classes. Worth adding if any logic is added.
-
-### Concerns
-`Concerns::DataFieldAccess`, `Concerns::PageCompat`, `Concerns::PhasedPageCompat` —
-tested indirectly via `data_field_spec.rb` and `page_union_spec.rb`.
-
----
-
-## Recommended next specs (priority order)
-
-1. **`Input::Page::Update.from_model` with `dataFields`** — now that field changes are
-   included, add a test that dirty fields appear in `dataFields.updates`.
-   File: extend `spec/ecoportal/api/graphql/input/page/update_spec.rb`
-
-2. **`StageCollection`** — `stages[name]`, `stages.get_by_name`, `stages.ordered`.
-   File: `spec/ecoportal/api/graphql/compat/stage_collection_spec.rb`
-
-3. **`SearchConf` filter translation in Registers** — v2 `date_filter` lbound→gte.
-   File: `spec/ecoportal/api/graphql/compat/registers_spec.rb` (filter translation only)

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

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