ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/projects/api-v2-to-graphql-migration/notes/cutover-usecase-gap-audit.md

@@ -1,139 +0,0 @@
-# Cutover gap audit — 3 use cases on GraphQL (TODO 8.5)
-
-## Update — 2026-06-29
-
-> Status refresh after the WRITE/value/submit path went **live-green** on `mini`. The full
-> mini automated suite now runs **35/35**. Several items the 2026-06-28 audit listed as gaps
-> or "coded-but-untested" are now RESOLVED and live-validated. History below is preserved;
-> read the per-use-case lines together with this block.
-
-**RESOLVED since the 2026-06-28 audit:**
-- **Field value round-trips (TODO 8.1) — DONE & LIVE-GREEN.** PlainText, Number, Select,
-  People (`people_ids`), CrossReference (`page_ids`/`reference_ids`) all round-trip
-  (set → `updatePage` → re-read → persisted). The P2 "coded-but-untested array writes"
-  (People `<<`, CrossRef `add`/`clear`) are now **validated live** — full mini suite 35/35.
-- **`submit!` / stage completion (TODO 8.2) — DONE & LIVE-GREEN.** Root cause of the old
-  stuck-stage failure: the stage carries a **review-task config**, so `completePageTask`
-  ALONE moves it to "reviewing" and never advances. Fix =
-  `updatePage(submit: true, task: { completePageTask: { signOff: true } })` — the inline
-  sign-off auto-approves the review and advances the stage. Gem gained sugar:
-  `Input::Page::Update.from_model(complete_page_task: { sign_off:, forced_complete:, notes: })`.
-  New test `compat_v2/page/submit_signoff_on_create` passes; old `stage_submit` flipped to the
-  confirmed call.
-- **Phased write-path identity (was P0 — "the most important gem fix") — RESOLVED & validated**
-  via `compat_v2/page/stage_write`: a value set through `stage.components` now persists through
-  `updatePage`. The `stage.components` vs flat `page.field_collection` dup'd-doc risk is closed.
-- **`get_by_name(type:)` — DONE** (2026-06-28).
-- **FilterTranslator `text_filter`→`match_filter`, `options_filter`→`one_of`/`none_of` — LANDED**
-  (commit 7725f96). Reclassified from a **code gap** to a **validation item**: still needs LIVE
-  validation against a real `registers.search` (see 8.3 below). Not a blocker for the translator
-  existing.
-
-**STILL OUTSTANDING (carry forward):**
-- **BasicPage reads (TODO 8.4)** — `CommonPageUnion` lacks `... on BasicPage { sections }`,
-  so basic pages get `corePageData` only. **IN PROGRESS** on branch `cutover/basicpage-sections`.
-- **Live-validate translated text/options filters (TODO 8.3)** — confirm `match_filter` /
-  `one_of`/`none_of` against a real `registers.search` on `mini`.
-- **Gem RSpec read-path regression specs (TODO 8.6)** — **IN PROGRESS** on branch
-  `cutover/regression-specs-8-6`.
-- **Collection-level write review (TODO 8.7)** — add/remove/reorder fields, multi-section
-  identity; deferred from the phased-flatten work.
-- **eco-helpers** — farmers must `include OozeRedirect` (else hits the dead v2 server);
-  `submit!` must pass `stageId` + map `force:` → `forced_complete:` (the gem now supports
-  `forced_complete:`; eco-helpers draft in progress).
-- **cans dedup rework** — membranes previews carry no field values (customer script).
-- **Release/pin the `pages` branch — HARD PREREQUISITE.** Released 1.3.4 lacks `base/page/`;
-  FieldPatches silently no-op against it.
-
----
-
-> Audited 2026-06-28 (background pass). Gem `pages` branch + eco-helpers OozeRedirect.
-> Two compat layers: the **gem** (`Compat::Pages`/`Registers` + native `DataField` DSL) and
-> **eco-helpers `OozeRedirect`** (`FieldPatches.apply!` monkey-patches the gem field classes
-> to add the v2-API methods `select`/`values`/`options`, CrossRef `add`/`clear`/`reference_ids`,
-> dirty `people_ids <<`, `submit!`, and the v2 `===` dispatch). The v2-API field methods come
-> from FieldPatches, NOT the gem. Memory: [[project-apiv2-cutover-usecases]].
-
-## Cross-cutting facts (verified)
-- `session.api(version: :oozes)` → `:v2` → **dead v2 server** unless `OozeRedirect#api_v2/apiv2`
-  aliases it to `graphql`. Only classes that `include OozeRedirect` get the redirect.
-- `Collection#get_by_name` took **one arg** (no `type:`) — **FIXED 2026-06-28** (added `type:`).
-- **Phased write-path identity risk (HIGH)** — **RESOLVED 2026-06-29** (see Update block).
-  *Original concern:* `DataField.new`/`Section.new` `.dup` their raw doc; a phased page builds
-  TWO independent `DataField::Collection`s (flat `page.field_collection` vs `Stage#components`
-  → `sections.components`), so mutating a field from `stage.components` might not reach the page
-  update payload. *Outcome:* `compat_v2/page/stage_write` confirms a value set via
-  `stage.components` now persists through `updatePage`. cans + toocs `with_fields` writes reach
-  the payload.
-
-## Per-use-case status
-**farmers / supplier_documents** (`Custom::UseCase`, **no OozeRedirect**, no stages):
-- 🔴 `api_v2 = session.api(version: :oozes)` → dead v2 server (no redirect). **Biggest gap** —
-  `include OozeRedirect` or switch to `session.api(version: :graphql)`. Despite the old "do
-  FIRST / most compat-friendly" note, farmers is the **least ready** (bypasses OozeRedirect).
-- 🟠 `options_filter` → `one_of`/`none_of` now **translated** in FilterTranslator (commit 7725f96);
-  needs LIVE validation against a real `registers.search` (8.3).
-- 🔴 Select `.values`/`.select`, CrossRef `.add` — FieldPatches-only; won't load for a
-  non-OozeRedirect class → NoMethodError.
-- ✅ (now) `get_by_name(..., type:)` — gem fix landed.
-- ✅ `registers.search` date_filter, `pages.get`/`get_new`/`create`/`update` (flat).
-- ✅ Field value round-trips (PlainText/Number/Select/People/CrossRef) — LIVE-GREEN 2026-06-29.
-
-**jamestrong / cans_upsert** (`OozeSamples::TargetOozesUpdateCase`, includes OozeRedirect, phased 'Details'):
-- 🟠 `text_filter` → `match_filter` now **translated** (commit 7725f96); needs LIVE validation (8.3).
-- 🔴 dedup via `page_result.membranes` — previews carry no field values; rework to fetch full
-  page per candidate or server-side filter.
-- 🟠 `submit!` sent with no `stageId` (script submits a specific stage) — eco-helpers must pass
-  `stageId`; draft in progress. (Stage *completion* mechanics now confirmed — see ✅.)
-- ✅ **phased write-path identity** — RESOLVED 2026-06-29 (`stage.components` writes persist via
-  `updatePage`; `compat_v2/page/stage_write`).
-- ✅ `submit!`/stage completion mechanics — confirmed 2026-06-29:
-  `updatePage(submit: true, task: { completePageTask: { signOff: true } })` advances a
-  review-task stage (`compat_v2/page/submit_signoff_on_create`).
-- ✅ search query, stage lookup, v2 `===` dispatch, PlainText/Number `value=`, Select
-  `select`/`values`/`options` (live-validated).
-
-**act-gov / toocs_coding** (`OozeSamples::TargetOozesUpdateCase`, includes OozeRedirect, phased 'Coding'):
-- ✅ People `people_ids <<` + CrossRef `add`/`clear` — **VALIDATED LIVE 2026-06-29** (the
-  previously-skipped array writes; full mini suite 35/35).
-- 🟠 `submit!(force: true)` — gem now supports `forced_complete:` (via
-  `from_model(complete_page_task: { forced_complete: })`); eco-helpers still needs to map
-  `force:` → `forced_complete:` and pass `stageId`. Draft in progress.
-- ✅ **phased write-path identity** — RESOLVED 2026-06-29 (same fix as cans; `stage_write`).
-- ✅ v2 `===` (People/CrossRef), CrossRef `reference_ids`/`clear`, stage lookup.
-
-## Prioritized remaining work
-
-> Re-prioritized 2026-06-29. The old P0 gem blockers (phased write-path identity, value
-> round-trips, submit!/stage advance) are RESOLVED & live-green. What remains is mostly
-> validation, eco-helpers/script wiring, and the release gate.
-
-**P0 (blockers):**
-1. **Release/pin `pages`** — released 1.3.4 lacks `base/page/`; FieldPatches silently no-op.
-   **HARD PREREQUISITE** for everything downstream.
-2. **farmers** — wire `include OozeRedirect` (or `session.api(version: :graphql)`) so it stops
-   hitting the dead v2 server. (script/eco-helpers)
-
-**P0 — RESOLVED 2026-06-29 (kept for history):**
-- ✅ **Phased write-path identity** — `stage.components` mutations now reach `updatePage`
-   (cans+toocs); validated `compat_v2/page/stage_write`. Was "most important gem fix".
-- ✅ **Field value round-trips (8.1)** — PlainText/Number/Select/People/CrossRef live-green.
-- ✅ **`submit!`/stage completion (8.2)** — review-task stage advances via inline sign-off.
-
-**P1 (functional gaps / validation):**
-3. ✅ `Collection#get_by_name(type:)` — DONE 2026-06-28.
-4. ✅ `FilterTranslator`: `text_filter`→`match_filter`, `options_filter`→`one_of`/`none_of`
-   — LANDED 2026-06-29 (commit 7725f96). **Now a validation item, not a code gap:** LIVE-validate
-   against a real `registers.search` (8.3). `compat/filter_translator.rb`.
-5. **BasicPage reads (8.4)** — add `... on BasicPage { sections }` to `CommonPageUnion`.
-   IN PROGRESS on branch `cutover/basicpage-sections`.
-6. **Gem RSpec read-path regression specs (8.6)** — IN PROGRESS on branch
-   `cutover/regression-specs-8-6`.
-7. **Collection-level write review (8.7)** — add/remove/reorder fields, multi-section identity.
-8. cans dedup rework (membranes → full-page fetch / server-side filter). (script)
-9. eco-helpers `submit!` — pass `stageId` + map `force:` → `forced_complete:` (gem supports it).
-   Draft in progress.
-
-**P2 (validate coded-but-untested):** ✅ People `<<` + CrossRef `add`/`clear` array writes
-— VALIDATED LIVE 2026-06-29 (mini suite 35/35). Remaining P2 validation = search filters
-live (8.3, folded into P1#4 above).

data/.ai-assistance/projects/compat-layer-audit/COMPAT_AUDIT.md

@@ -1,244 +0,0 @@
-# GraphQL COMPAT Layer Audit — contract fidelity vs ecoportal-api-v2
-
-> READ-ONLY audit. No code changed, no git touched. Date: 2026-07-08.
-> Scope: every place the GraphQL gem re-expresses a v2 public API, measured against the
-> v2 contract as source of truth. Consumers surveyed: `multi_org_api/*/config/ooze_cases`,
-> eco-helpers `usecases/graphql` + `OozeRedirect` + `ooze_samples`.
-
----
-
-## 1. Executive verdict — AD-HOC PATCH, not a faithful mirror
-
-Oscar is **right**. The compat layer is a set of reactive, per-symptom patches, not a
-contract-faithful mirror of the v2 API. Concrete evidence:
-
-1. **Same method, three different return-type decisions, no shared contract.** `get_by_name`
-   is a COLLECTION in v2 for components, forces, and bindings, but a SINGLE for stages. The
-   gem got forces (`base/force/collection.rb:16` → `select`), bindings
-   (`base/force/binding_collection.rb:19` → `select`), and stages
-   (`compat/stage_collection.rb:34` → `find`, correct) right — but got **components wrong**
-   (`base/page/data_field/collection.rb:35` → `find`) and **sections' `get_by_heading` wrong**
-   (`base/page/section_collection.rb:31` → `find`, v2 is `select`). Three files, four
-   independent return-type choices. A faithful mirror would have one rule per v2 method; this
-   has ad-hoc choices that happen to match in some files and not others.
-
-2. **The downstream consumer already contains a workaround for the gem's wrong return type.**
-   eco-helpers `OozeRedirect#with_fields` wraps the component lookup:
-   `[collection.get_by_name(label)].compact` (`ooze_redirect.rb:187`) — i.e. it treats
-   `get_by_name` as returning a SINGLE and re-wraps it into an array to fake the v2 collection
-   contract. That is a patch compensating for a patch. When the gem is made faithful (returns a
-   collection), this line double-wraps → `[[Field]]`. Whack-a-mole in the flesh.
-
-3. **Two conflicting `#components` definitions on the same object.** `Concerns::PageCompat#components`
-   returns `dataFields || []` (`page_compat.rb:22`); `Concerns::DataFieldAccess#components`
-   returns `field_collection` (`data_field_access.rb:22`). Both are `include`d in
-   `Interface::BasePage` (`base_page.rb:6-7`), DataFieldAccess second so it wins — but the dead
-   PageCompat version returning a raw array is a fossil of an earlier, incompatible attempt.
-
-4. **Methods the v2 contract guarantees are simply absent** (not deliberately dropped —
-   nobody enumerated the contract): `DataField::Collection` has no `get_by_id`, no
-   `get_by_type` returning a `reference?`-style API, no `unattached`/`multi_section`;
-   `SectionCollection` has no `get_by_id`, no `ordered`-by-weight, no `between`. Consumers call
-   `components.get_by_id` and `sections.get_by_id` today (§3).
-
-5. **`components.add` has different semantics** — v2 `upsert!`s into the live collection so a
-   later `get_by_name` finds it; the gem stashes into a private `@additions` array
-   (`collection.rb:53-60`) that `each`/`get_by_name` never see.
-
-The through-line: each method was added when a specific script broke, choosing whatever return
-shape that one script needed — never derived from the v2 method's documented contract. That is
-the definition of ad-hoc.
-
----
-
-## 2. Divergence catalog
-
-Severity: **S1** = silent wrong result / breaks live consumers; **S2** = raises / missing method;
-**S3** = latent (no current consumer but contract-divergent).
-
-| # | Method | v2 contract (file:line) | gem compat (file:line) | Divergence | Sev | Affected consumers |
-|---|--------|-------------------------|------------------------|------------|-----|--------------------|
-| C1 | `components.get_by_name(name, type:)` | `select` → **Array** (`v2/page/components.rb:37`) | `find` → **single DataField** (`base/page/data_field/collection.rb:35`) | Return type: collection vs single | **S1** | act-gov `.first`/`.last`, farmers `.first`, and ~120 `components.get_by_name(...).first` call-sites across multi_org_api (twg, tng, briscoes, alexander, argenta, whittlesea…); eco-helpers `ooze_redirect.rb:184,187` |
-| C2 | `sections.get_by_heading(h, mild:)` | `ordered.select` → **Array** (`v2/page/sections.rb:61`) | `find` → **single Section** (`base/page/section_collection.rb:31`) | Return type + drops `mild:` + no weight-ordering | **S1** | `tng_env_update_case.rb:19` (`.get_by_heading("Details").first`) |
-| C3 | `components.get_by_id(id)` | `find` → single (`v2/page/components.rb:21`) | **absent** on `DataField::Collection` | Missing method → `NoMethodError` | **S2** | `event_changes_case.rb:50` (`components.get_by_id(fld.reference_id)`); eco-helpers `ooze_update_case.rb:10` |
-| C4 | `sections.get_by_id(id)` | `find` → single (`v2/page/sections.rb:46`) | **absent** on `SectionCollection` | Missing method → `NoMethodError` | **S2** | `TnG_Active_sitefix_part2_case.rb:106` |
-| C5 | `components.add(...)` | `upsert!` into live collection; found by later `get_by_name`/`each` (`v2/page/components.rb:53`) | stashes in private `@additions`; NOT in `@fields`; later `get_by_name`/`each` miss it (`collection.rb:53-60`) | Mutation semantics diverge | S2 | any multi-step add-then-read script; `add` kwargs also differ (`id:` required, `doc:` shape) |
-| C6 | `sections.get_by_type(t)` | `ordered.select` → Array (`v2/page/sections.rb:53`) | `select` → Array but **not weight-ordered** (`section_collection.rb:25`) | Ordering: v2 orders by weight, gem uses response order | S3 | ordering-sensitive section scripts (latent) |
-| C7 | `components.get_by_type(t)` | `select` → Array, no ordering (`v2/page/components.rb:28`) | `select` → Array (`collection.rb:27`) | **Match** (return type) | ok | argenta `remove_edit_events_case.rb:21,29` (uses `.select` on result — works only because both are Arrays) |
-| C8 | `forces.get_by_name(name)` | `select` → Array (`v2/page/forces.rb:36`) | `select` → Array (`base/force/collection.rb:16`) | **Match** | ok | all `forces.get_by_name(...).first` sites |
-| C9 | `force.bindings.get_by_name(name, type:)` | `select` → Array (`v2/page/force/bindings.rb:102`) | `select` → Array but **drops `type:` kwarg** (`binding_collection.rb:19`) | Partial: arity narrower | S3 | bindings callers pass name only today; `type:` unused |
-| C10 | `stages.get_by_name(name)` | `find` → single (`v2/page/stages.rb:17`) | `find` → single (`compat/stage_collection.rb:34`) | **Match** | ok | eco-helpers `ooze_base_case.rb:109,144`, `register_export_case.rb:137` |
-| C11 | `stages[id_or_name]` | v2 CollectionModel `[]` by key (id) | id **or** name (`stage_collection.rb:27-30`) | Superset (name-fallback) — benign but non-contract | S3 | eco-helpers `stages[id] || stages.get_by_name` (belt-and-braces) |
-| C12 | `forces.get_by_id`, `.ordered`, `.bindings_by_reference` | present (`v2/page/forces.rb:29,64,20`) | **absent** on gem `Force::Collection` | Missing methods | S3 | not called by surveyed consumers (latent) |
-| C13 | `bindings.get_by_id / get_by_type / get_by_reference / reference? / by_name / by_reference` | present (`v2/page/force/bindings.rb:82,92,68,61,26,42`) | **absent** on gem `BindingCollection` | Missing methods | S3 | not called by surveyed consumers (latent) |
-| C14 | `sections.ordered` (by weight) | `sort_by weight` (`v2/page/sections.rb:86`) | returns `@sections` as-is (`section_collection.rb:41`) | Ordering not applied | S3 | latent |
-| C15 | `page.components` (page-level) | v2 components collection | **two conflicting defs**: PageCompat returns `dataFields`/`[]` array (`page_compat.rb:22`), DataFieldAccess returns `Collection` (`data_field_access.rb:22`); include order (`base_page.rb:6-7`) makes DataFieldAccess win, PageCompat one is dead code | Latent footgun / dead code | S2 | any refactor reordering includes silently swaps behaviour |
-| C16 | `entry.components.get_by_name(...).detect{…}` | Array#detect works on v2 collection | gem returns single → `.detect` = `Enumerable#detect` on a **DataField** (iterates its doc?) | Return-type breakage | **S1** | `risks_migration_case.rb:89` (`.get_by_name("Review frequency:").detect{…}`) |
-| C17 | `force.bindings.get_by_name(x).empty?` | Array#empty? | gem Array → ok (C8/C9 correct) | ok | tng `tng_env_update_case.rb:112` |
-
-### Folded-in prior findings (verified against current code)
-
-These are not `get_by_name`-style return-type bugs but are part of the same "compat built ad hoc"
-thread — the read/write CONVERTER contract was never systematically mirrored. Cross-referenced
-against `.ai-assistance/code/model_input_mapping/SYNTHESIS.md` (2026-07-07). **Note:** SYNTHESIS
-marks several as FIXED on `feature/model-input-fixes` (current branch); status below reflects that.
-
-| # | Prior finding | Current status (verified) | File:line |
-|---|---------------|---------------------------|-----------|
-| P1 | `passarray`/`embeds_many` don't diff via `as_update` (otherTags, locations, filterTags) | **FIXED** — `DIFF_CLASS = Diffable::LeafDiffService` now on `Interface::BasePage` | `interface/base_page.rb:13` |
-| P2 | `IdDiff` set-diff machinery non-functional (ContractorEntity/Action) | Reported FIXED via `id_diff_fields` macro (SYNTHESIS §3.2); **not re-verified in this pass** — flagged for confirm | — |
-| P3 | File/Image/Contractor readers use write-key → `[]` | Reported FIXED (SYNTHESIS §3.3); Image fragment `images[].id` was the blocker | `base/page/data_field/{file_field,image_gallery,contractor_entities}.rb` |
-| P4 | DataField read-key ≠ write-key (shape asymmetry) | Partly FIXED (CrossReference was template); File/Image/Contractor per P3 | `.ai-assistance/code/refactoring/datafield-readwrite-shape-asymmetry.md` |
-| P5 | `SnakeCamelAccess` is a one-way method_missing shim, no specs | **STILL TRUE** — `concerns/snake_camel_access.rb`; no spec file exists (`Glob spec/**/snake_camel*` → none). One-way (snake→camel only); silently no-ops single-word methods (`parts.length < 2` → returns as-is) | `concerns/snake_camel_access.rb:50-54` |
-
----
-
-## 3. Comprehensive fix plan (contract-faithful) + spec risk
-
-The organising principle: **derive each collection method from the v2 method it mirrors, not from
-the one script that broke.** Recommend a small shared helper module so components/sections/forces/
-bindings collections share one contract per method name.
-
-### Fix C1 — `DataField::Collection#get_by_name` → collection (`select`)
-
-Faithful fix: return `pool.select { … }` (mirror `v2/page/components.rb:37`), keeping `type:`.
-
-**Risks these EXISTING gem specs (they assume single return):**
-- `spec/.../base/page/data_field_spec.rb:397-399` — `coll.get_by_name('name').id` → must become `.first.id`
-- `data_field_spec.rb:408` — `coll.get_by_name('Name').value = 'Bob'` → `.first.value =`
-- `data_field_spec.rb:419` — same
-- `data_field_spec.rb:463` — `field = coll.get_by_name('Name')` → `.first`
-- `base/page/phased/stage_spec.rb:72` — `stage.components.get_by_name('Description').value` → `.first.value`
-- `compat/stage_collection_spec.rb:92` — `stage.components.get_by_name('Description').value` → `.first.value`
-- `compat/stage_view_spec.rb:57` — `view.components.get_by_name('Summary').value` → `.first.value`
-- `input/page/update_spec.rb:136` — `page_with_fields.components.get_by_name('Note').value = 'New'` → `.first.value =`
-- `integration/toocs_submit_replay_spec.rb:38` — `page.components.get_by_name('Coding completed by:')` → `.first`
-
-These 9 spec sites LOCK IN the wrong behaviour and must be updated in lockstep with the fix
-(add `.first`). They also confirm the gem's own test suite was written to the ad-hoc behaviour,
-not the v2 contract.
-
-**Also requires a coordinated eco-helpers change:** `ooze_redirect.rb:184-187` — line 187
-`[collection.get_by_name(label)].compact` must become `collection.get_by_name(label)` (already an
-Array), and line 184-185 `field = collection.get_by_name(label); … [field] : []` must select over
-the collection. This is the cross-repo lockstep the audit brief warns about: a "just remove
-`.first`" workaround in org scripts is itself a dirty patch that re-breaks here.
-
-### Fix C2 — `SectionCollection#get_by_heading` → collection (`select`), add `mild:`, order by weight
-
-Faithful: `ordered.select { same_string?(s.heading, h, mild: mild) }`. Add a `same_string?`
-helper (case-insensitive; `mild:` = alnum-only compare per v2). Requires §Fix-C14 (`ordered` by
-weight) for exact parity.
-
-**Spec risk:** no existing gem spec asserts `get_by_heading` (Grep found none) → **no green
-specs go red.** Add new specs (§4). Consumer `tng_env_update_case.rb:19` already does `.first`, so
-it starts working correctly.
-
-### Fix C3 / C4 — add `get_by_id` to `DataField::Collection` and `SectionCollection`
-
-`find { |x| x.id == id }` (mirror v2). **No spec risk** (new methods). Add coverage.
-
-### Fix C5 — `components.add` upserts into the live collection
-
-Faithful: push the built field into `@fields` (or an upsert-by-id) so later `get_by_name`/`each`
-find it, and keep `dirty_additions` sourced from those. **Spec risk:** check `data_field_spec.rb`
-add-section (`:451-465`) — the deletion test reads `get_by_name('Name')` (existing field, fine);
-the add tests assert `dirty_additions` only, so upserting into `@fields` needs a guard that
-`dirty_inputs` (updates) does not double-count additions. Design the split carefully; lock with a
-"add then get_by_name finds it" spec.
-
-### Fix C6 / C14 — order `get_by_type`/`ordered` by weight in `SectionCollection`
-
-Only if sections carry a weight in the GraphQL doc (verify fragment exposes it; if not, response
-order is the only signal and this stays a documented gap). **No current spec risk.**
-
-### Fix C9 / C12 / C13 — fill missing force/binding contract methods + `type:` on bindings
-
-Add `get_by_id`, `get_by_type`, `get_by_reference`, `reference?`, `by_name`, `by_reference`,
-`ordered`, `bindings_by_reference`, and honour `type:` in `binding.get_by_name`. These are S3
-(no live consumer) — do them to make the mirror complete, not urgently. **No spec risk.**
-
-### Fix C15 — delete the dead `PageCompat#components`
-
-Remove `PageCompat#components` (`page_compat.rb:21-24`); it is shadowed and returns the wrong
-shape if include order ever changes. `page_compat_spec.rb:39-43` asserts `components` is a
-`DataField::Collection` — that stays green (DataFieldAccess provides it). **No spec risk.**
-
-### Fix P5 — add specs (and ideally make two-way) for `SnakeCamelAccess`
-
-At minimum add characterization specs. Consider reusing eco-helpers' polished hash-level
-snake/camel module rather than the bespoke `method_missing` shim (per memory
-`project_snake_camel_access`). Scope decision for Oscar.
-
-### Recommended structural change (kills the class of bug)
-
-Extract a shared `Concerns::V2CollectionContract` (or a `Base::Page::CollectionModel`) that
-defines `get_by_id` (single), `get_by_name`/`get_by_heading`/`get_by_type` (collection, per v2),
-`ordered`, `same_string?(mild:)` **once**, and have DataField/Section/Force/Binding collections
-include it. This turns "one return-type decision per file" into "one contract, four includes" —
-the actual remedy for the ad-hoc philosophy.
-
----
-
-## 4. Test strategy
-
-### Gem rspec additions (lock the CONTRACT, not the current behaviour)
-- **Return-type contract specs**, one per collection, asserting `get_by_name`/`get_by_heading`
-  return `Array` (C1, C2) and `get_by_id` return a single (C3, C4). Assert `.first` on a
-  multi-match returns the first; assert empty match returns `[]` (not nil) for the collection
-  methods — this is the exact shape act-gov `.first`/`.last` and farmers `.first` depend on.
-- **Add-then-find spec** (C5): `coll.add(id:…){…}; expect(coll.get_by_name(label)).to include(the added)`.
-- **`mild:` parity spec** for `get_by_heading` (C2).
-- **Cross-object consistency meta-spec:** a single spec that asserts all four collections agree
-  on the return type of `get_by_name` (guards against future drift — the root cause here).
-- Update the 9 spec sites listed under Fix-C1 to `.first` in the SAME commit as the fix.
-- Add `SnakeCamelAccess` characterization spec (P5).
-
-### eco-helpers spec additions
-- Update `OozeRedirect#with_fields` (`ooze_redirect.rb:184-189`) and add a spec proving it
-  returns the same shape (Array) whether the field exists or not, against a faithful collection.
-- Regression spec replaying an act-gov-style `get_by_name(...).first` / `.last` through the
-  OozeRedirect path.
-
-### Integration coverage (parity harness, training mini-site)
-- On the all-21-fields template mini-org, run the A/B parity harness (memory
-  `project_parity_test_plan`): execute one representative ooze case using `.get_by_name(...).first`
-  and `.get_by_heading(...).first` against BOTH v2 and GraphQL, assert identical selected field
-  IDs and identical emitted mutation input. **Needs live creds** (mini-site API token) — the only
-  part of this plan that cannot run in CI without secrets.
-- Replay act-gov `20240130_act_disease_title_update_case.rb` (`.first`+`.last`) and the farmers
-  case in `-simulate` mode post-fix to confirm no `.first`-on-single or double-wrap breakage.
-
----
-
-## 5. Open questions / could not verify
-
-1. **P2/P3 fix status not re-verified.** SYNTHESIS says the IdDiff macro and File/Image/Contractor
-   readers were fixed on this branch; I did not re-open those files this pass. Confirm before
-   relying on them.
-2. **Section weight in the GraphQL fragment.** C6/C14 (order-by-weight) only achievable if the
-   section fragment actually returns a `weight`/ordering field — not confirmed. If absent, response
-   order is the contract and these stay documented gaps.
-3. **`components.add` write path.** Whether an added field can even be created via the current
-   `dataFields.updates`/additions mutation shape without a server-side `buildFromTemplate` ID is a
-   separate question (the collection comment at `collection.rb:47` says it "must reference an
-   existing server-side ID"). Faithful `add` semantics may be bounded by the mutation API.
-4. **Full green-suite baseline.** I did not run `bundle exec rspec`; the 9 spec sites are
-   identified statically. Run the suite before/after to get exact red counts.
-5. **`get_by_type` ordering for components (C7).** v2 does not order components by weight either,
-   so gem matches — but confirm no consumer relies on component order.
-
----
-
-## Appendix — files inspected
-
-v2 contract: `ecoportal-api-v2/lib/ecoportal/api/v2/page/{components,forces,sections,stages}.rb`,
-`.../page/force/bindings.rb`.
-Gem compat: `lib/.../base/page/data_field/collection.rb`, `.../base/page/section_collection.rb`,
-`.../base/force/{collection,binding_collection,force}.rb`,
-`.../compat/{pages,registers,stage_collection,stage_view}.rb`,
-`.../concerns/{page_compat,data_field_access,snake_camel_access,deprecation}.rb`,
-`.../interface/base_page.rb`.
-Consumers: `multi_org_api/*/config/ooze_cases/*` (grep, ~120 sites),
-`eco-helpers/lib/eco/api/usecases/graphql/compat/ooze_redirect.rb`, `.../ooze_samples/*`.
-Prior findings: `.ai-assistance/code/model_input_mapping/SYNTHESIS.md`.

data/.ai-assistance/projects/dynamic-model-generation/INTENT.md

@@ -1,93 +0,0 @@
-# Project: Dynamic / Auto-generated GraphQL Models
-
-**Created:** 2026-06-05
-**Status:** idea — not started
-**Depends on:** `ecoportal-api-v2-doublemodel-review` project (DoubleModel must be stable first)
-
----
-
-## Goal
-
-Explore generating the `ecoportal-api-graphql` model layer from the GraphQL schema, rather
-than hand-authoring Ruby classes for every type. Two variants to evaluate:
-
-- **Static generation** — run a generator at gem-build time (or as a developer task) that
-  produces Ruby source files from schema introspection. Output is committed and readable.
-- **Dynamic generation** — generate model classes at Ruby load time (per execution), from
-  the live schema or a cached schema file.
-
----
-
-## Motivation
-
-The current hand-authored model layer requires manual updates whenever the ecoPortal GraphQL
-schema evolves. Auto-generation would eliminate that maintenance burden and make the client
-automatically up to date with the schema.
-
----
-
-## Hard Constraints
-
-These are non-negotiable design requirements, arising from how the `ecoportal-api-*` gem
-family is used in practice:
-
-### 1. Transparency to the source of backend issues
-
-The `ecoportal-api-*` gems are deliberately designed so that when an ecoPortal backend
-returns an unexpected response, the problem is easy to trace — there is static code to
-read and point to. Integration teams and the engineering team both rely on this to avoid
-prolonged debates about whether a bug is client-side or server-side.
-
-Any model generation approach must preserve this traceability. Concretely:
-
-- A generated (or dynamically created) model class must produce a log entry (at an
-  appropriate level) when it encounters a field it did not expect, or when a field it
-  expected is absent from the response.
-- Silent field drops, silent type coercions, and silent diff misses are not acceptable.
-- Where auto-generation is used, there must be a deterministic and inspectable record
-  of what was generated and from which schema version — ideally committed source files
-  for the static variant, or a structured schema-version log for the dynamic variant.
-
-### 2. Integration with `ecoportal-api-v2` DoubleModel
-
-The `as_update` / `as_input` diff pipeline relies on the `DoubleModel` contract:
-`doc` (current state), `original_doc` (server-confirmed state), `initial_doc` (state
-at render time). Auto-generated models must honour this contract fully — including
-cascaded diff, `root?` / `read_only?` semantics, and `patch_ver` propagation.
-
-This is why this project depends on the DoubleModel review being complete first: the
-contract must be stable and well-specified before we try to generate classes that
-implement it.
-
-### 3. Render-to-mutation conversion gap
-
-GraphQL schema definitions cannot express how a render model converts to a mutation
-input model. This is a permanent gap in the GraphQL specification. Any model generation
-approach must either:
-- Generate the render model only, leaving mutation input classes hand-authored (acceptable),
-- Or provide a deterministic, scriptable convention for deriving mutation input shapes
-  from render models — not an AI-generated approximation.
-
-Ad-hoc or AI-generated conversion code is not acceptable as the primary mechanism here,
-because it cannot be deterministically verified.
-
----
-
-## Open Questions
-
-- Static vs dynamic: the dynamic variant is technically more interesting but harder to
-  debug when a field silently misroutes a diff. Static generation + commit is more
-  transparent. Which is the right default?
-- Can the `DoubleModel` contract be expressed as a generator template robustly enough
-  to produce correct `doc` / `original_doc` handling for Array-indexed (CollectionModel)
-  paths? This is likely the hardest part.
-- How do we handle schema evolution between gem releases? Version-lock the schema file?
-  Validate at load time?
-
----
-
-## Out of scope until DoubleModel review is complete
-
-Do not begin design or implementation of this project until
-`.ai-assistance/projects/ecoportal-api-v2-doublemodel-review` reaches a stable conclusion
-on the `doc` memoization and sync semantics.