ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/projects/ooze-graphql-native-migration/DECISIONS.md

@@ -0,0 +1,161 @@
+# Decisions — Ooze → Native GraphQL Migration
+
+Seeded with the founding architectural decisions. Append per-case parity results and any
+new decisions as the project executes. Never delete entries — history matters.
+
+---
+
+## [2026-06-30] Strangler-fig migration, one case at a time
+
+**Context:** The ooze use-case stack runs on APIv2 via the `OozeRedirect` runtime shim. We
+need it on native GraphQL, but a big-bang rewrite would (a) risk all live customer scripts
+at once and (b) collide with the in-flight `fix/ooze-redirect-faithful-dryrun` work.
+
+**Options considered:**
+1. Big-bang rewrite of the whole ooze tree.
+2. Keep the shim indefinitely.
+3. Strangler-fig: build native classes beside the old ones, migrate one case at a time,
+   each parity-gated, retiring shim code incrementally.
+
+**Decision:** Option 3 (strangler-fig), sequenced parent-before-child along the inheritance
+tree, gated by the A/B parity harness per case.
+
+**Reason:** Incremental, reversible, keeps live scripts working throughout, and lets us
+delete shim code in safe slices instead of one terrifying commit.
+
+**Consequences:** Old and new implementations coexist for the duration; the inventory
+partition (Phase 0) is the master schedule; each phase has an explicit parity gate.
+
+---
+
+## [2026-06-30] Native classes are the REAL implementation — NOT a monkeypatch
+
+**Context:** The current approach (`OozeRedirect.included` → `FieldPatches.apply!` +
+`base.prepend(Infrastructure)`) is a monkeypatch: it reopens v2 field classes globally and
+prepends behaviour onto the host case. The developer explicitly corrected the design:
+**do NOT keep reopening/patching classes ("patch at the end of each class").**
+
+**Options considered:**
+1. Continue patching: make the GraphQL/samples classes by reopening the OozeSamples classes.
+2. Make the new `graphql/samples/pages/*` classes the canonical implementation; old names
+   become thin subclasses/delegators.
+
+**Decision:** Option 2. The native `GraphQL::Samples::Pages::*` class holds the real logic.
+`Eco::API::UseCases::OozeSamples::*` names are redefined as thin subclasses (or delegators)
+of the native class.
+
+**Reason:** Monkeypatching is what produced the 2026-06-30 KPI/dry-run-loss bug (a patched
+control-flow method silently diverged from the base loop). A real class with an explicit
+loop has one source of truth and is testable in isolation. Subclassing is a stable,
+well-understood compatibility idiom; runtime class reopening is not.
+
+**Consequences:** `FieldPatches`' global v2-class reopening (`patch_v2_type_dispatch!`) and
+the GraphQL field `prepend`s become unnecessary — native cases dispatch on GraphQL types
+directly. They are removed as the last case needing them is flipped (Phase 7).
+
+---
+
+## [2026-06-30] Preserve the OozeSamples public class names as the BC surface
+
+**Context:** Downstream customer scripts subclass/include the public names
+(`OozeSamples::TargetOozesUpdateCase`, `RegisterUpdateCase`, `Helpers::Creatable`,
+`RegisterExportCase`, etc.) and define override points (`process_ooze`, `search`,
+`filters`, `custom_processing`, `excluded_field_hooks`). The include-shim's whole value is
+that scripts change **nothing** today.
+
+**Decision:** The public `OozeSamples::*` / `OozeCases::*` names, their `name '...'`
+registrations, `type :other`, class-level `batch_size`/`register_id`, attr_readers, and
+every documented override point are **preserved exactly**. They resolve to the native
+implementation via subclass/delegation.
+
+**Reason:** Zero-script-edit is the explicit success criterion. The names are the contract.
+
+**Consequences:** Phase 0 must inventory every include/subclass site and override-method
+set so the native classes expose identical surfaces. Any unavoidable script edit is a goal
+regression → log here and confirm with Oscar before proceeding.
+
+---
+
+## [2026-06-30] Per-case parity gating via the A/B harness before flipping
+
+**Context:** Each migrated case changes the execution backend for real customer data. We
+need objective proof of equivalence before flipping the public name.
+
+**Decision:** Before flipping any old name to the native class, the case must be
+**parity-proven** against the existing v2 case using the team's A/B parity harness on the
+`mini` test org (read-only parity first, then writes). The recorded result is the gate.
+
+**Reference:** memory `project-parity-test-plan` — all-21-DataField-type template in `mini`,
+(1) A/B standalone harness (e.g. `mini/graphql_parity/`) reading/writing through both
+`ecoportal-api-v2` and `Ecoportal::API::GraphQL` + `Compat::Pages`, diffed by the field
+matrix; (2) eco-helpers session-backend swap re-running a real script unchanged. Also
+`.ai-assistance/projects/eco-helpers-compat/`.
+
+**Reason:** The 21-type field matrix gives a concrete pass/fail spec; the live-script swap
+proves the production path. Cheaper than discovering divergence in a customer run.
+
+**Consequences:** Phase 0 captures v2 baselines (the "A" side); the harness must exist
+before Phase 2 (built in Phase 0 if not). Each phase records its parity result as a dated
+entry in this log.
+
+---
+
+## [2026-06-30] Sequence: RegisterUpdateCase + Creatable, then TargetOozesUpdateCase, first
+
+**Context:** Two cases are already exercised in the live cutover: act-gov TOOCS coding
+(`TargetOozesUpdateCase`) and jamestrong CANS upsert (`RegisterUpdateCase` +
+`Helpers::Creatable`). `TargetOozesUpdateCase` **inherits** `RegisterUpdateCase`.
+
+**Decision:** Migrate the native register base + `Creatable` first (Phase 2, CANS), then
+`TargetOozesUpdateCase` (Phase 3, TOOCS), because the child cannot be native until its
+parent is.
+
+**Reason:** Highest live value, and the inheritance order forces parent-first. These two
+also surface the full KPI/queue/dedup/dry-run/submit machinery, de-risking later cases.
+
+**Consequences:** Phase 1 (shared concerns) must land first so both cases stay thin.
+
+---
+
+## [2026-06-30] Forces-dependent cases are HELD pending a Phase 0 live readiness test (not assumed-blocked)
+
+**Context (corrected 2026-06-30):** the GraphQL force endpoint is NOT read-only or missing —
+the gem ships both `Query::PageWithForces` (read) AND `Mutation::Page::ExecuteForceCommands`
+→ `executeWorkflowCommands` (write: `editForce`/`addBinding`/`removeBinding`/`removeForce`).
+What is unconfirmed: `OozeRedirect.force_support?` is hard-wired `false`, and a (possibly stale)
+`ooze_redirect.rb` comment claims `PageWithForces` fails schema validation / backend "in
+progress". `ooze_redirect.rb` lists ~50% of all ooze cases as force-dependent.
+
+**Decision:** Do NOT assume forces are blocked. Phase 0 **live-tests** read + a no-op write
+against a real org. If it passes, forces are IN scope and those cases migrate normally. If it
+fails, they are partitioned **"migratable now"** vs **"blocked on forces"** and stay on the v2
+path; `force_compat.rb` / the v2 fallback is retained **only** for that holdout until the
+endpoint is fixed.
+
+**Blocked-on-forces seed list (from `ooze_redirect.rb`):** act-gov (5× `20240130_act_*`,
+`rearrage_page_sites`), briscoes (`remove_induction_sections`, `310524_Briscoes_Remove_Tasks`),
+chorus (4× `audit_update`), hcc (`update_enterprise_risk`), lic (`update_life_cycle_force`),
+mitre10 (`rich_text_update`, `update_location_force`, `updating_template`), npdc
+(`contractor_title_force`, `risk_titile_force`, `fix_title_syncing`, `reminder_date_fields`,
+`10092024_NPDC_CP_Add_Force`), profile-group (`int_training_review`,
+`20231026_profile_wellness`), turners-growers (`event_changes`, `inj_cost_calc`,
+`remove_line_force`), twg (`hide_attached_risks`, `add_new_force`).
+
+**Reason:** No endpoint = no native path. Forcing it would either break or require fetching
+via the broken force query for every case (the exact trap `force_support?` guards against).
+
+**Consequences:** This is a **hard external dependency**. The project completes "Phase 7"
+with the forces holdout explicitly documented, not deleted. Track the endpoint's arrival as
+the trigger for the follow-up forces-migration project.
+
+---
+
+## Per-case parity results (append as completed)
+
+<!-- Template:
+## [DATE] Parity result — <CaseName>
+**Harness run:** <link/path to A/B output, e.g. baselines/<case>.txt vs native run>
+**Field matrix:** <pass/fail per relevant DataField type>
+**Live script re-run:** <org/script, unchanged? parity?>
+**Decision:** flip / hold / fix-first
+-->

data/.ai-assistance/projects/ooze-graphql-native-migration/INTENT.md

@@ -0,0 +1,125 @@
+# Project: Ooze Use-Cases → Native GraphQL Migration (strangler-fig)
+
+**Created:** 2026-06-30
+**Status:** active
+**Primary repo:** `eco-helpers` (`C:\ruby_scripts\git\eco-helpers`)
+**Companion repo:** `ecoportal-api-graphql` (`C:\ruby_scripts\git\ecoportal-api-graphql`)
+**Branch (eco-helpers):** `feature/ooze-graphql-native-migration` (cut from current `fix/ooze-redirect-faithful-dryrun` once that merges)
+**Target branch:** `master` (eco-helpers) / `main` (gem)
+
+> **Why this plan lives in the gem repo:** `eco-helpers` has no `.ai-assistance/projects/`
+> folder. The team's project-cycle structure is hosted in `ecoportal-api-graphql`
+> (alongside the related `eco-helpers-compat` project), so this plan is committed here
+> for continuity. **The code work, however, is almost entirely in `eco-helpers`.**
+> Cross-reference: `.ai-assistance/projects/eco-helpers-compat/` (the compat layer this
+> migration eventually retires the *shim half* of).
+
+---
+
+## Goal
+
+Migrate the eco-helpers **ooze use-case stack** off the transitional APIv2 `OozeRedirect`
+monkeypatch shim and onto **native GraphQL use-case classes**, incrementally, one case at a
+time, using a strangler-fig approach.
+
+The new native implementations live under
+`lib/eco/api/usecases/graphql/samples/pages/*` (cases) and
+`lib/eco/api/usecases/graphql/helpers/pages/*` (shared concerns). The **existing public
+class names** under `Eco::API::UseCases::OozeSamples::*` are preserved as the
+backwards-compatibility surface — they become thin subclasses / delegators of the native
+classes. Downstream customer scripts keep working with **zero edits**, exactly as the
+include-shim achieves today.
+
+---
+
+## Motivation
+
+### The shim is fragile and lossy
+
+`OozeRedirect` (`lib/eco/api/usecases/graphql/compat/ooze_redirect.rb` +
+`ooze_redirect/{dirty_array,field_patches,force_compat}.rb`) is a **runtime monkeypatch**:
+
+- `OozeRedirect.included(base)` calls `FieldPatches.apply!`, which **reopens** v2 field
+  classes (`PlainTextField`, `SelectionField`, `ReferenceField`, `PeopleField`,
+  `NumberField`) to make `===` / `is_a?` lie, and `prepend`s anonymous modules onto the
+  GraphQL field classes (`Base::Page::DataField::{People,CrossReference,Select}`) and
+  `Interface::BasePage`. These patches are **global, process-wide, and order-sensitive**.
+- It then `base.prepend(Infrastructure)` to override instance methods on the host case.
+
+**The recent bug (2026-06-30, captured in memory `session-handoff-ooze-redirect-dryrun`):**
+an earlier version of the shim's `Infrastructure` module **replaced whole control-flow
+methods** (`with_each_entry`, `update_ooze`, and wrapped `process_ooze`) rather than
+adapting only the leaf v2 operations. Effects observed on the act-gov (toocs) and
+jamestrong (cans) `-simulate` runs:
+
+- KPI counters (Search / Retrieved / Updated / Created) all read **0** — the base loop's
+  increments were bypassed.
+- The dry-run diff **never printed** — the compat `process_ooze` did `return if simulate?`
+  with no feedback, and the base `display_patch` / `backup_patch!` / `dirty?` read
+  `patch_doc(ooze)['page']` while the gem's `Compat::Pages#get_body` returned a **flat**
+  `as_update` (no `'page'` key) → `"No changes to update"` misfired.
+
+That bug was patched on `fix/ooze-redirect-faithful-dryrun` by **slimming the shim back to
+leaf adaptations and reusing the base loop** (gem: `get_body` → `{ 'page' => as_update }`
+and `update` folds captured submit flags; eco-helpers: removed the control-flow overrides).
+But the episode proves the structural point: **a monkeypatch that has to second-guess the
+host class's control flow is intrinsically dangerous.** Every future change to the
+OozeSamples base loop risks silently re-breaking the redirect, and vice-versa.
+
+### Native classes are the durable answer
+
+Making the **GraphQL samples the real implementation** — with their own explicit loop, KPI
+tracking, dry-run feedback, and field access — removes the need to patch v2 classes or
+intercept the host's control flow at all. The old names survive purely as a compatibility
+veneer (subclass / delegate), which is a stable, well-understood Ruby idiom.
+
+---
+
+## Scope
+
+### In scope
+
+- New native GraphQL use-case classes under `lib/eco/api/usecases/graphql/samples/pages/*`,
+  mirroring the OozeSamples case tree (the **migratable-now** subset — see Risks).
+- Shared concerns extracted to `lib/eco/api/usecases/graphql/helpers/pages/*`
+  (creatable, ooze-handlers, shortcuts, filters, rescuable, dirty/patch feedback).
+- Specs **in eco-helpers** for each native counterpart, written **before/with** the class
+  (specs-first / parity-proving).
+- Re-pointing the old `OozeSamples::*` names to delegate to / subclass the native classes,
+  **case by case**, behind per-case parity gating.
+- Per-case removal of the now-dead redirect code (the relevant `Infrastructure` overrides
+  and `FieldPatches` entries) once a case is flipped.
+- Final removal of the `OozeRedirect` shim entirely once all migratable cases are flipped.
+
+### Out of scope (non-goals)
+
+- **Force / binding-dependent cases.** ~50% of ooze cases use `target.forces` /
+  `force.bindings` / `force.custom_script`. The gem DOES ship GraphQL force client code for
+  both read (`Query::PageWithForces`) and write (`executeWorkflowCommands`:
+  `editForce`/`addBinding`/`removeBinding`/`removeForce`), but it is gated OFF
+  (`OozeRedirect.force_support?` hard-wired `false`) and end-to-end readiness is UNCONFIRMED.
+  These cases are **held pending a Phase 0 live readiness test** — in scope if it passes, on
+  the v2 path if it fails. See the Risks section.
+- Rewriting customer scripts. Scripts must not change. If a script *must* change, that is a
+  decision to log in DECISIONS.md and confirm with Oscar — it is a regression of the goal.
+- Template mutation, Workflow Builder, webhooks/subscriptions (separate projects).
+- The `eco-helpers-compat` gem-side compat layer itself (`Compat::Pages`,
+  `Compat::Registers`, `StageView`) stays — the native cases call it. This project retires
+  the **OozeRedirect monkeypatch**, not the compat façade.
+
+---
+
+## Success Criteria
+
+1. `TargetOozesUpdateCase` and `RegisterUpdateCase` (+ `Helpers::Creatable`) run on native
+   GraphQL classes, parity-proven against the v2 path via the A/B harness, with the old
+   names still resolving and the two live cutover scripts (act-gov TOOCS, jamestrong CANS)
+   running **unchanged**.
+2. Every migratable OozeSamples case has a native counterpart, a passing spec suite, and a
+   recorded parity result before its name is flipped.
+3. The `OozeRedirect` shim (and its `FieldPatches` global monkeypatches) is **deleted** for
+   all migrated cases; the only remaining v2 coupling is in the explicitly force-blocked
+   cases.
+4. `bundle exec rspec` green in eco-helpers; gem suite still green.
+5. No customer script edits required — verified against the downstream include-site
+   inventory from Phase 0.

data/.ai-assistance/projects/ooze-graphql-native-migration/RISKS.md

@@ -0,0 +1,126 @@
+# Risks & Blockers — Ooze → Native GraphQL Migration
+
+---
+
+## BLOCKER (external dependency, UNCONFIRMED): GraphQL forces not yet verified end-to-end
+
+**~50% of all ooze cases use forces** (`target.forces`, `force.bindings.{get_by_name,add,
+delete!}`, `force.custom_script`, `force.script`).
+
+**Correction (2026-06-30):** the GraphQL force endpoint is NOT simply "missing" — the gem
+already carries client code for BOTH read and mutate:
+- **Read:** `Ecoportal::API::GraphQL::Query::PageWithForces` fetches `page.forces { ...ForceFields }`.
+- **Mutate:** `Mutation::Page::ExecuteForceCommands` → the `executeWorkflowCommands` mutation,
+  supporting `editForce { id, customScript }`, `addBinding`, `removeBinding`, `removeForce`
+  (plus `addForce`/`reorderForces` `WorkflowCommandInput` variants). So a force WRITE path
+  exists via the workflow-command bus — it is **not** read-only at the client layer.
+
+What is still UNCONFIRMED (and why this stays a blocker until verified live, not via code-read):
+- `OozeRedirect.force_support?` is hard-wired to return `false`
+  (`lib/eco/api/usecases/graphql/compat/ooze_redirect.rb`) — forces are gated OFF.
+- The `ooze_redirect.rb` comment claims `PageWithForces` currently fails schema validation
+  (selections on PageUnion; `id` on `DataFieldBinding`/`SectionBinding`; unused `ForceFields`)
+  and that the backend is "in progress" — but that note may be STALE given the mutation classes
+  now present. **Phase 0 must live-test PageWithForces + a no-op editForce against a real org**
+  to establish actual readiness rather than trusting the comment.
+- Activating `ForceCompat` on the mere *existence* of those classes would make **every**
+  OozeRedirect case (even non-force ones like TOOCS) fetch via a possibly-broken force query.
+
+**Impact:** Force-dependent cases are **held pending the Phase 0 live readiness test** of
+`PageWithForces` + `executeWorkflowCommands`. If that test passes, forces come INTO scope and
+these cases migrate like any other (just with an extra force-command write path). If it fails,
+they are partitioned into the "blocked on forces" table in `INVENTORY.md` and remain on the v2
+path, and the `OozeRedirect` shim cannot be deleted in full until either (a) all blocked cases
+are retired by the customer, or (b) the endpoint is fixed and a follow-up project migrates them.
+
+**Blocked-on-forces seed list** (from `ooze_redirect.rb` lines 68–77 — re-verify in Phase 0):
+
+| Org | Cases |
+|---|---|
+| act-gov | 5× `20240130_act_*_case`, `rearrage_page_sites_case` |
+| briscoes | `remove_induction_sections`, `310524_Briscoes_Remove_Tasks` |
+| chorus | 4× `audit_update` |
+| hcc | `update_enterprise_risk_case` |
+| lic | `update_life_cycle_force_case` |
+| mitre10 | `rich_text_update`, `update_location_force`, `updating_template` |
+| npdc | `contractor_title_force`, `risk_titile_force`, `fix_title_syncing`, `reminder_date_fields`, `10092024_NPDC_CP_Add_Force` |
+| profile-group | `int_training_review`, `20231026_profile_wellness` |
+| turners-growers | `event_changes`, `inj_cost_calc`, `remove_line_force` |
+| twg | `hide_attached_risks`, `add_new_force` |
+
+**Mitigation / trigger:** Phase 0 live-tests `PageWithForces` (read) and a no-op
+`editForce`/`addBinding` via `executeWorkflowCommands` (write) against a real org. If both pass,
+restore a real `force_support?` readiness check, fold forces into the main migration scope, and
+drop this from the blocker list. If either fails, track the fix with Engineering and keep the
+cases above on v2; do not delete `force_compat.rb` or the v2 fallback path that serves them.
+
+---
+
+## Risk: monkeypatch regressions during coexistence
+
+While native and shim coexist, the global `FieldPatches` (v2-class `===`/`is_a?` reopening,
+GraphQL field `prepend`s) remain process-wide. A native case loaded in the same process as
+a shimmed case shares those patches.
+
+**Mitigation:** Native cases must not *depend* on the patches (they dispatch on GraphQL
+types directly). Spec the native classes in isolation **without** loading `OozeRedirect`, to
+prove independence. Only retire a given `FieldPatch` once the last case needing it is
+flipped (tracked in DECISIONS.md).
+
+---
+
+## Risk: silent behavioural divergence (the bug that motivated this)
+
+The 2026-06-30 incident (KPIs read 0, dry-run diff suppressed) was a *silent* divergence
+between the shim and the base loop. Native rewrites can re-introduce silent divergence
+(e.g. a KPI counter or dedup edge missed).
+
+**Mitigation:** Per-case A/B parity gate against the captured v2 baseline (KPI block + diff)
+is mandatory before flipping. Specs must assert the full KPI set and the dry-run diff shape
+(`get_body(page)['page']`), not just "it ran".
+
+---
+
+## Risk: BC surface drift (a missed override point)
+
+If a native class omits an override point a customer script relies on (e.g. `search`,
+`filters`, `custom_processing`, `excluded_field_hooks`, `paired_fields_post_callback`,
+`to_field`, `before_loading_new_target`), that script breaks — a goal regression.
+
+**Mitigation:** Phase 0 `INVENTORY.md` enumerates every override method per consumer
+script. Native classes must expose every one. Re-run each affected live script unchanged as
+the final per-phase check.
+
+---
+
+## Risk: write-path / field-type gaps in the gem
+
+The compat layer has known gaps (from `eco-helpers-compat/INTENT.md`): `add_field` /
+`components.add` (`dataFields.additions`) not implemented; file/image upload unimplemented;
+some field types read-only. A case that needs an unsupported write cannot reach parity.
+
+**Mitigation:** The 21-type field matrix (parity plan) classifies clean-write vs partial vs
+read-only. A case requiring a gap is **held** (logged in DECISIONS.md) until the gem closes
+the gap — not flipped. `RegisterMigrationCase` (typed field copy) is the highest-exposure
+case here.
+
+---
+
+## Risk: interactive prompts in automated runs
+
+The base loop reintroduces the v2-faithful `prompt_user` "proceed (y/N)" preview
+(local default 'N', 10s timeout). Native cases reproduce this; an automated/remote run that
+expects no prompt could hang or abort.
+
+**Mitigation:** Preserve the existing `run_mode_remote?` → default 'Y' behaviour and the
+timeout exactly as the v2 cases have it. Cover it in specs.
+
+---
+
+## Risk: scope creep into the compat façade or forces
+
+This project retires the **OozeRedirect monkeypatch**, not the `Compat::Pages`/`Registers`
+façade (native cases call it) and not forces.
+
+**Mitigation:** Non-goals are explicit in INTENT.md. Forces work is a separate project
+gated on the endpoint.