ecoportal-api-graphql 1.3.13 → 1.3.16

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

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

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

@@ -1,261 +0,0 @@
-# TODOs — Ooze → Native GraphQL Migration
-
-Legend: `[ ]` todo · `[~]` in progress · `[x]` done · `[!]` blocked (see Risks/DECISIONS)
-
-Each phase ends with a gate. **Do not flip an old class name to delegate until that
-case's parity result is recorded in DECISIONS.md.**
-
-> **STATUS 2026-07-02:** Phase 0 inventory DONE → see `INVENTORY.md`. Scope narrowed by Oscar:
-> **build the native GraphQL classes ONLY this cycle** — no delegation flip, no shim removal yet
-> (those come "long after we know everything works on the native samples"). So Phases 1–2 (native
-> classes + specs) are IN; the flip/removal steps stay `[ ]` until Oscar green-lights.
-
----
-
-## Phase 0 — Inventory & Baseline (no code changes)  ✅ DONE 2026-07-02 (see INVENTORY.md)
-
-### 0a. Map the full ooze case inheritance/include tree
-- [ ] Confirm the inheritance chain (verified 2026-06-30, re-confirm before building):
-  - `Common::Loaders::UseCase`
-    - `OozeSamples::OozeBaseCase` — `include Helpers`, `include Helpers::Rescuable`
-      - `OozeSamples::OozeRunBaseCase` (single-ooze runner)
-        - `OozeSamples::OozeUpdateCase`
-          - `OozeSamples::OozeFromDocCase`
-      - `OozeSamples::RegisterUpdateCase` — `include Helpers::Creatable`
-        - `OozeSamples::TargetOozesUpdateCase`  ← **first cutover case** (act-gov TOOCS)
-        - `OozeSamples::RegisterMigrationCase` — `include HelpersMigration`
-    - `OozeSamples::RegisterExportCase` (standalone — NOT under OozeBaseCase)
-      - `OozeCases::ExportRegisterCase` — `include Helpers::ExportableRegister`
-- [ ] Map the helper module surface each case relies on:
-  - `OozeSamples::Helpers` aggregate → `Shortcuts`, `Filters`, `OozeHandlers`,
-    `Creatable`, `Rescuable`, `ExportableOoze`, `ExportableRegister`
-  - `OozeSamples::HelpersMigration` → `Copying`, `TypedFieldsPairing`
-- [ ] For each helper, classify: **v2-coupled** (references
-  `Ecoportal::API::V2::Page::*`, e.g. `OozeHandlers#merge_values`, `Shortcuts#object_reference`,
-  `Filters#field_key_name`) vs **pure** (string/array utils — `Shortcuts#same_string?`,
-  `simplify_string`, `OozeHandlers#merge_arrays`). Pure helpers port verbatim; v2-coupled
-  helpers need GraphQL-typed re-expression.
-- [ ] Record which case methods are leaf v2 ops vs control flow (the line that the shim bug
-  blurred): control flow = `main`, `with_each_entry`, `update_ooze`, `update_oozes`,
-  `process_ooze`, `ooze`, `new_target`, the KPI counters, dry-run feedback. Leaf ops =
-  field/stage access, `apiv2.pages.{get,get_new,create,update,get_body}`,
-  `apiv2.registers.search`.
-
-### 0b. Inventory every downstream script include site (BC surface)
-- [ ] In the training repo (`C:\ruby_scripts\implementation\training`) and any other
-  consumer repos, grep for the public names that scripts subclass/include:
-  - `OozeSamples::OozeBaseCase`, `OozeRunBaseCase`, `OozeUpdateCase`, `OozeFromDocCase`
-  - `OozeSamples::RegisterUpdateCase`, `TargetOozesUpdateCase`, `RegisterMigrationCase`
-  - `OozeSamples::RegisterExportCase`, `OozeCases::ExportRegisterCase`
-  - `OozeSamples::Helpers::Creatable` and any other helper included directly
-  - `GraphQL::Compat::OozeRedirect` (the include line scripts add today)
-- [ ] Produce `INVENTORY.md` in this folder: per public name, list (a) every consumer
-  script that subclasses/includes it, (b) which overridable methods that script defines
-  (`process_ooze`, `search`, `filters`, `custom_processing`, `excluded_field_hooks`, etc.),
-  (c) whether the script touches forces (→ blocked partition).
-- [ ] **Forces live readiness test (decides the partition below).** Do NOT assume forces are
-  blocked — the gem ships read (`Query::PageWithForces`) AND write
-  (`executeWorkflowCommands`: `editForce`/`addBinding`/`removeBinding`/`removeForce`) client
-  code, gated off via `OozeRedirect.force_support? == false`. Against a real org: (a) run
-  `PageWithForces` on a force-bearing page and confirm the query is schema-valid + returns
-  populated forces; (b) run a no-op `editForce`/`addBinding` via `executeWorkflowCommands` and
-  confirm it round-trips. Record the verdict — it determines whether forces are IN scope.
-- [ ] **Partition the inventory into two tables: "migratable now" vs "blocked on forces"**
-  — gated on the readiness test above. If forces pass, there is NO blocked partition. If they
-  fail, seed the blocked list from `ooze_redirect.rb` lines 68–77 (act-gov, briscoes, chorus,
-  hcc, lic, mitre10, npdc, profile-group, turners-growers, twg). This partition is the
-  master schedule for Phases 2..N.
-
-### 0c. Capture the v2 baseline behaviour (parity reference)
-- [ ] For each migratable case, run the existing v2 path under `-simulate` against the
-  `mini` test org and save the dry-run diff + KPI block as the golden reference
-  (`baselines/<case>.txt`). This is the A side of every later A/B comparison.
-- [ ] Confirm the A/B parity harness exists / is buildable — see memory
-  `project-parity-test-plan` (all-21-field template in `mini`, A/B standalone harness in
-  e.g. `mini/graphql_parity/`, plus the eco-helpers session-backend swap). If the harness
-  is not yet built, that is a prerequisite sub-task here, not in Phase 2.
-
-**Gate 0:** INVENTORY.md complete, partitioned, and baselines captured for the migratable set.
-
----
-
-## Phase 1 — Extract shared concerns to `graphql/helpers/pages/*`
-
-Goal: build the native shared substrate **before** any case, so case classes stay thin.
-Mirror the existing native helper convention (`graphql/helpers/base/{case_env,graphql_env,
-error_handling}.rb`, `graphql/samples/pages/page/base.rb`).
-
-- [ ] `graphql/helpers/pages.rb` — namespace aggregator (mirrors `helpers/location.rb`).
-- [ ] `graphql/helpers/pages/shortcuts.rb` — port the **pure** `OozeSamples::Helpers::Shortcuts`
-  methods (`same_string?`, `simplify_string`, `titleize`, `normalize_string`,
-  `clean_question`, `to_i`, `is_number?`). Re-express `object_reference` for GraphQL
-  page/section/component model types (drop the `Ecoportal::API::V2::*` `case/when`).
-- [ ] `graphql/helpers/pages/filters.rb` — port `Filters`, re-expressing `field_key_name`
-  for GraphQL field types (`value.ref_backend` / `value.label` → GraphQL equivalents).
-- [ ] `graphql/helpers/pages/ooze_handlers.rb` — re-express `merge_values` `case/when` against
-  `Base::Page::DataField::*` subclasses instead of `V2::Page::Component::*`; `merge_arrays`
-  is pure → port verbatim.
-- [ ] `graphql/helpers/pages/rescuable.rb` — port `Rescuable` (validate base type ==
-  `GraphQL::Base` instead of `Common::Loaders::Base`).
-- [ ] `graphql/helpers/pages/creatable.rb` — native `Creatable`: `creating_new_page`,
-  `drafting_entry` (→ `graphql.pages.get_new`), `create_entry`/`create_ooze`
-  (→ `graphql.pages.create`), with dry-run feedback. Base-type guard → native register case.
-- [ ] `graphql/helpers/pages/patch_feedback.rb` — extract the dry-run/dirty machinery that
-  the shim bug exposed: `dirty?(page)` (`!as_update.nil?` OR pending submit/sign-off),
-  `display_patch` / `backup_patch!` reading `graphql.pages.get_body(page)['page']`,
-  `dry_run_feedback` + `DRY_COUNT` sampling. **This is the one-source-of-truth replacement
-  for the bug-prone shim-vs-baseloop split.**
-- [ ] Spec each helper module in `spec/eco/api/usecases/graphql/helpers/pages/*_spec.rb`.
-- [ ] `bundle exec rubocop` clean on all new helper files.
-
-**Gate 1:** helper specs green; no production case yet depends on them (pure addition).
-
----
-
-## Phase 2 — `RegisterUpdateCase` + `Helpers::Creatable`  (jamestrong CANS upsert)
-
-> Sequenced first alongside Phase 3 because both are exercised in the live cutover and
-> `TargetOozesUpdateCase` **inherits** `RegisterUpdateCase`. Build the parent first.
-
-- [ ] Build native `GraphQL::Samples::Pages::Register::Base` (working title) under
-  `graphql/samples/pages/register/base.rb`, modelled on the existing
-  `graphql/samples/pages/page/base.rb` (KPIs, `each_page`, `update_page`, `simulate?` guard)
-  but reproducing the **RegisterUpdateCase** semantics faithfully:
-  - batched search via `graphql.registers.search` / `graphql.pages.each(searchConf:)`
-  - dedup by page id (`ooze_result_ids`), queue/`enqueue`/`queue_shift` batching
-  - full KPI set: total_search / retrieved / non_retrieved / dupped / updated /
-    failed_update / attempted_updates / created / create_attempts (match `kpis_message`)
-  - `before_loading_new_target` flush-on-requeue behaviour
-  - `results_preview` + interactive `prompt_user` proceed (y/N) (v2-faithful)
-- [ ] `include GraphQL::Helpers::Pages::Creatable` + `PatchFeedback` + `Shortcuts`.
-- [ ] **Specs first:** `spec/eco/api/usecases/graphql/samples/pages/register/base_spec.rb`
-  — cover KPI counting, dedup, dry-run diff printing, create path, submit/sign-off fold.
-  Port the assertions from `spec/.../compat/pages_spec.rb` regression specs where relevant.
-- [ ] **Parity-prove** against the v2 `RegisterUpdateCase` baseline using the A/B harness on
-  `mini` (read-only first, then a 1-row CANS-style upsert). Record result in DECISIONS.md.
-- [ ] **Flip the old name:** make
-  `Eco::API::UseCases::OozeSamples::RegisterUpdateCase` a thin subclass/delegator of the
-  native class (preserve `name 'register-update-case'`, `batch_size`, attr_readers,
-  `process_ooze` override point, `main(..., mode: :legacy|:delegate)` signature).
-  `OozeSamples::Helpers::Creatable` → delegate to / alias the native `Creatable`
-  (keep `validate_base_type!` accepting the native register base).
-- [ ] **Remove shim code for this case:** delete the redirect paths now dead for register
-  cases. (Keep `FieldPatches` until the *last* case that needs them is flipped — track in
-  DECISIONS.md which patches each flip retires.)
-- [ ] Re-run jamestrong CANS script **unchanged** on `mini`; confirm parity with baseline.
-
-**Gate 2:** CANS parity recorded; old `RegisterUpdateCase` name resolves to native; eco-helpers suite green.
-
----
-
-## Phase 3 — `TargetOozesUpdateCase`  (act-gov TOOCS coding)
-
-- [ ] Build native counterpart subclassing the Phase-2 native register base, reproducing
-  `TargetOozesUpdateCase`: CSV `target_ids` source, `batched_target_ids`,
-  `target_ids_preview` (duplicate detection + proceed prompt), `with_each_entry` over ids.
-- [ ] **Specs first:** id-batching, duplicate detection, requeue-flush, KPI counts,
-  cross-reference set + submit (the TOOCS coding shape), dry-run diff.
-- [ ] **Parity-prove** against the v2 `TargetOozesUpdateCase` baseline (act-gov TOOCS,
-  1-row CSV) on `mini`. Record in DECISIONS.md.
-- [ ] **Flip the old name** `OozeSamples::TargetOozesUpdateCase` → native subclass.
-- [ ] Remove now-dead shim code for this case.
-- [ ] Re-run act-gov TOOCS script **unchanged**; confirm parity.
-
-**Gate 3:** TOOCS parity recorded; old name resolves to native; both live cutover scripts green on native.
-
----
-
-## Phase 4 — `OozeBaseCase` / `OozeRunBaseCase` / `OozeUpdateCase` / `OozeFromDocCase` (single-ooze chain)
-
-> Single-ooze runners (`options[:source][:ooze_id]`). Lower live-traffic but needed for
-> completeness and as the base several scripts subclass directly.
-
-- [ ] Native `GraphQL::Samples::Pages::Ooze::Base` reproducing `OozeBaseCase`
-  (target, `process_ooze` block contract, `new_page`/`create_page`, `with_fields`/
-  `with_sections`/`with_stage`, dry-run feedback via `PatchFeedback`).
-- [ ] Native single-ooze runner (`OozeRunBaseCase`: `ooze_id`/`stage_id` from options,
-  `exit_if_no_changes!`, `prompt_to_confirm!`).
-- [ ] Native `OozeUpdateCase` (`to_field` resolver — drop the v2 `Component`/`Binding`
-  branches; resolve via GraphQL `components.get_by_id` / name match).
-- [ ] Native `OozeFromDocCase` (docx table reading is v2-agnostic — port; only the field
-  access underneath changes).
-- [ ] Specs for each; parity-prove each single-ooze runner on `mini`.
-- [ ] Flip names `OozeBaseCase` → `OozeRunBaseCase` → `OozeUpdateCase` → `OozeFromDocCase`
-  bottom-up; remove dead shim code per flip.
-
-**Gate 4:** single-ooze chain on native; names preserved; specs + parity recorded.
-
----
-
-## Phase 5 — `RegisterMigrationCase` (+ `HelpersMigration`)
-
-> Heaviest helper surface (`copy_pairings`, `copy_generic_paired_fields`,
-> `copy_mapped_fields`, typed-field pairing). Confirm none of the target customer
-> migrations rely on forces before scheduling (Phase 0 partition decides this).
-
-- [ ] Port `HelpersMigration::{Copying,TypedFieldsPairing}` to
-  `graphql/helpers/pages/migration/*`, re-expressing typed-field copy against GraphQL
-  `DataField::*` types (the v2 `Component` type matrix → GraphQL type matrix).
-- [ ] Native `RegisterMigrationCase` subclassing the native register base; reproduce the
-  field-maps json loading, `custom_processing`/block contract, `report_*` pairing reports.
-- [ ] Specs (typed copy correctness is the high-risk area — cover each field type's copy).
-- [ ] Parity-prove a real migration on `mini` (src→dst page, diff field-by-field via the
-  21-type matrix from the parity plan).
-- [ ] Flip name; remove dead shim code.
-
-**Gate 5:** migration parity recorded (field-type matrix); name preserved.
-
----
-
-## Phase 6 — Export cases (`RegisterExportCase`, `OozeCases::ExportRegisterCase`)
-
-> Read-only (no update path) → safest. `RegisterExportCase` is **not** under `OozeBaseCase`
-> and has its own `ooze`/`stage`/`apiv2` — note `build_full_ooze` stitches all stages into
-> one `PageStage` (a v2-specific merge GraphQL gets for free by fetching the full page).
-
-- [ ] Native `GraphQL::Samples::Pages::Register::Export` reproducing `RegisterExportCase`
-  (batched search, `build_full_ooze` → simply the full GraphQL PageUnion, no stage stitch).
-- [ ] Port `Helpers::ExportableRegister` / `ExportableOoze` to native (CSV header/values
-  generation over GraphQL fields; honour `only_indexed`/`only_labeled`/`only_with_ref`).
-- [ ] Native `ExportRegisterCase` (tags/date-range filters via native `Filters`).
-- [ ] Specs (CSV header + row parity against v2 export of the same register on `mini`).
-- [ ] Flip names; remove dead shim code.
-
-**Gate 6:** export CSV byte-parity (or documented intentional diffs) on `mini`.
-
----
-
-## Phase 7 — Retire the OozeRedirect shim entirely
-
-- [ ] Confirm every **migratable** case is flipped and no migratable consumer still
-  `include`s `GraphQL::Compat::OozeRedirect`.
-- [ ] Delete `lib/eco/api/usecases/graphql/compat/ooze_redirect.rb` and the
-  `ooze_redirect/{dirty_array,field_patches}.rb` parts **for all retired patches**.
-  - [ ] **Keep** `ooze_redirect/force_compat.rb` + the minimal include path **iff** any
-    force-blocked case still rides the v2 path and needs it. Otherwise delete too.
-- [ ] Remove the `FieldPatches.apply!` global v2-class reopening (`patch_v2_type_dispatch!`)
-  and GraphQL field `prepend`s — these only existed to make v2 `case/when` dispatch work;
-  native cases dispatch on GraphQL types directly.
-- [ ] Verify **no customer script edits were needed** against the Phase 0 inventory; any
-  script that still references a removed symbol is a defect to fix in this project, not a
-  customer change.
-- [ ] Full `bundle exec rspec` green in eco-helpers; gem suite green; rubocop clean.
-- [ ] Update `eco-helpers` CHANGELOG; update memory + this project's status → complete.
-
-**Final gate:** shim deleted (modulo the explicitly-documented forces holdout), all names
-preserved, zero script edits, suites green.
-
----
-
-## Standing constraints (apply in every phase)
-
-- [ ] Specs-first for each native class (parity-proving) — never flip a name before its
-  spec suite and recorded parity result exist.
-- [ ] Native class is the **real implementation**; old `OozeSamples::*` name is a thin
-  subclass/delegator. **Never reopen/monkeypatch a class to migrate it.**
-- [ ] Preserve every public class name, `name '...'` registration, `type :other`,
-  class-level `batch_size`/`register_id`, attr_readers, and documented override points.
-- [ ] Each flip removes the shim code it makes dead — but only retire a `FieldPatch` once
-  the last case needing it is flipped (track in DECISIONS.md).
-- [ ] Follow the working-tree safety protocol
-  (`.ai-assistance/conventions/code-working-tree-protocol.md`) for every eco-helpers change.

data/.ai-assistance/projects/ooze-graphql-native-migration/analysis/2026-06-30-cutover-workflow-deep-review.md

@@ -1,122 +0,0 @@
-# Deep review — TOOCS + CANS cutover workflow (2026-06-30)
-
-Exhaustive pre-live audit of the two production dry-runs (act-gov TOOCS coding, jamestrong
-CANS upsert) on branch `fix/ooze-redirect-faithful-dryrun`. Goal: trust nothing that "looks
-clean", enumerate every hypothesis (however unlikely), prove/disprove each with code evidence,
-fix what's real, and harden what's latent. Four parallel sub-investigations fed this; verdicts
-and fixes below. All gem fixes are committed with specs; full suite 465/0/2 pending, rubocop clean.
-
-## The two dry-run bodies under audit
-
-TOOCS (after the stageId fix — now correct):
-```
-{:id=>"6a3225532b97b00073c23aa8", :patchVer=>229,
- :stageId=>"6a3225522b97b00073c22d7d", :submit=>true,
- :task=>{:completePageTask=>{:forcedComplete=>true}},
- :dataFields=>{:updates=>[{:people=>{:id=>"6a3225522b97b00073c22cea",
-                                     :peopleIds=>["65d6d3dcacb0b3000773f547"]}}]}}
-```
-CANS (update-shaped body, but the entry was actually a CREATE — see H8/H-create):
-```
-{:id=>"656e802f2d489c005ad0a6af", :patchVer=>22,
- :dataFields=>{:updates=>[ 5×plainText, 2×number (one =0.0), 1×select ]}}
-```
-
----
-
-## Findings table (every hypothesis explored)
-
-| # | Hypothesis | Verdict | Action |
-|---|---|---|---|
-| H1 | People `<<` REPLACES (wipes) existing people | **NOT a bug on normal path** — DirtyArray seeds from the read; backend is full-replace but gem sends the full set. | — |
-| H1b | People reader has no fallback → wipe if read returns `peopleIds:null` while `people{id}` nodes exist | **LATENT risk** (real, not active under $content reads) | **FIXED** — reader falls back to `people` nodes |
-| H2 | `peopleIds` is the wrong input key | **NOT a bug** — backend `PeopleInput.people_ids: [ID]`, flat array (not IdDiff). | — |
-| H3 | Number empty CSV cell → `0.0` written over server value | **CONFIRMED footgun** — `"".to_f == 0.0`, no blank guard | **FIXED** — `value=` blank→nil |
-| H4 | Select shape (all options w/ selected flags) wrong | **NOT a bug** — matches `OptionInput{id,selected}`; merge+deselect semantics; sending only-selected would fail to deselect | — |
-| H5 | PlainText `""` clear is unintended | **NOT a bug** — schema String, real clear; dirty vs baseline | — |
-| H6 | Phantom-dirty (PlainText/Number/Select) vs baseline | **NOT a bug** — diff uses `original_doc`; no read/write key asymmetry for these types | — |
-| H7 | Value types wrong (Float/String/Boolean) | **NOT a bug** — match backend input types | — |
-| H8 | CANS upsert mis-routes existing page → create (duplicate risk) | **NOT a bug** — routing by `search_by_id`; the entry genuinely was NOT found → correct CREATE; no duplicate risk | — |
-| H9 | CANS KPIs lie ("Total 0 / Created out of 1 / Updated 0") | **NOT a bug** — numerically correct: 0 existing targets, 1 create attempt, dry-run so 0 created | — |
-| H-create | CANS create dry-run previews as "would **update**" (wrong envelope: draft id+patchVer, no templateId) | **CONFIRMED display bug** — `new_draft?` only checked `patchVer.nil?`, but buildFromTemplate drafts carry a patchVer | **FIXED** — `_compat_source_template_id` marker |
-| H10 | The new stageId guard breaks other ooze cases | **NOT a bug** — only TOOCS+CANS submit on the GraphQL path, both via `with_stage` → stage resolves; metlifecare is pure APIv2 | — |
-| H11 | TOOCS recorded stageId is the wrong stage | **NOT a bug (by construction)** — StageView records the RESOLVED 'Coding' stage id; replay spec asserts it | — (verify id in UI) |
-
----
-
-## Confirmed bugs + fixes (all gem, all spec-covered)
-
-### 1. Number blank → 0.0 (live-corruption footgun) — `base/page/data_field/number.rb`
-`def value=(numeric); doc['value'] = numeric&.to_f; end` coerces `""` to `0.0` (Ruby `"".to_f`).
-The CANS case assigns `fld.value = row[csv_header]&.strip` with no blank guard, so an empty CSV
-numeric cell wrote a real `0.0`, and the diff (correctly) shipped it over the server value.
-**Fix:** blank (nil / empty / whitespace string) → `nil`, never `0.0`; genuine numbers still
-coerce to Float. Specs: 8 cases (string/Numeric/"0"/""/whitespace/nil/clear-over-value/no-op).
-**Residual:** a non-numeric garbage string (`"abc"`) still `.to_f`→`0.0` — lesser concern, noted.
-**Caller policy:** whether a blank should CLEAR vs be LEFT ALONE is the case's call (TOOCS skips
-blanks for people; CANS does not for numbers) — the gem only guarantees blank ≠ 0.0.
-
-### 2. People reader has no node fallback (latent wipe) — `base/page/data_field/people.rb`
-Reader read only `doc['peopleIds']`; if a response ever returned it null/empty while the
-`people{id}` nodes were populated, `people_ids << x` would seed from `[]` and the full-replace
-backend would WIPE the field. **Fix:** fall back to the `people` nodes when `peopleIds` is blank
-(mirrors CrossReference's `references.nodes` fallback). Read key == write key, so no phantom-dirty.
-Specs: fallback read, append-preserves-from-nodes, prefer-peopleIds-when-both-present.
-
-### 3. CANS create dry-run mislabel — `compat/pages.rb` + `interface/base_page.rb`
-A `buildPageFromTemplate` draft carries a server patchVer, so `new_draft?` (patchVer-nil only)
-classified it as an update → the create previewed as "would update" with a misleading envelope.
-The read fragment fetches neither `draft` nor `sourceTemplateId`, so neither could be used.
-**Fix:** `Compat::Pages#get_new` records `_compat_source_template_id` (new accessor on
-`Interface::BasePage`); `new_draft?` treats that marker as the authoritative create signal;
-`create_body` uses it for the templateId. Specs: get_new sets marker, marked-draft-with-patchVer
-previews as create (templateId, no patchVer). Affects DRY-RUN ONLY (live create already correct).
-
----
-
-## Verified-correct (no action)
-- **People append preserves** existing people (DirtyArray seeds from read; gem sends full set;
-  backend `set_people_ids` is full-replace, so sending the full set is exactly right). `peopleIds`
-  is the correct flat `[ID]` key (backend `PeopleInput`).
-- **Select** "all options with selected flags" is correct and is the only shape that reliably
-  DESELECTS (`SelectBuilder` merges by id; options not sent are untouched).
-- **PlainText `""`** is a legitimate clear; **dirty** baselines on `original_doc` for all three
-  scalar/array types; **value types** match backend inputs.
-- **CANS routing**: existing→update, missing→create, decided by `search_by_id`; no duplicate-create.
-  The KPIs are numerically correct. (The "would update" wording was the only defect — fixed.)
-- **Guard blast radius**: only TOOCS + CANS submit on the GraphQL path; both via `with_stage`
-  (records the active stage) → guard satisfied. metlifecare `resident_events` is pure APIv2.
-
-## Backend evidence (from C:\docker\ecoPortal_master, via sub-investigations)
-- `app/graphql/types/fill_in_page/inputs/data_fields/people_input.rb` → `people_ids: [ID]` flat.
-- `app/services/new_ep/pages/assign_attributes_service.rb:175` → `set_people_ids` = full replace.
-- `select_builder.rb` → merge-by-id; deselect requires sending `selected:false`.
-- `{plain_text,number}_input.rb` → `String` / `Float` value types.
-
----
-
-## Open questions — RESOLVED / remaining (updated 2026-07-01)
-1. **CANS field `...61` `value=>0.0` — RESOLVED: real zero, not an artifact.** The CANS CSV row
-   `FE15TR04715` has `STANDARD COST` = `0` (UNQUOTED literal) → `"0".to_f == 0.0`, correctly sent.
-   (`SITE="15"` → `…60 = 15.0`.) Confirmed against `QEST_Components_20260629.csv`. The Number fix
-   was never implicated in this value.
-   - **Eco::CSV empty-cell behavior (verified, `eco-helpers/lib/eco/csv.rb`):** `Eco::CSV.parse`
-     = `{headers: true, skip_blanks: true}` + stdlib `::CSV` with NO `nil_value`/`empty_value`
-     override → **unquoted** empty (`,,`) becomes `nil`; **quoted** empty (`""`) stays `""`. The
-     feed mixes both (e.g. `CUSTOMER_ITEM=""` → `""` → surfaced as `plainText value:""`). So a
-     quoted-empty NUMERIC cell WOULD hit `"".to_f → 0.0` — the Number/Gauge `blank→nil` fix is the
-     correct safety net even though this particular row didn't trigger it. ("empties → nil" only
-     holds for unquoted empties.) `skip_blanks` skips whole-blank ROWS, not empty cells.
-   - **Gauge had the identical footgun** (`numeric&.to_f`) — now fixed the same way. Both Number
-     and Gauge route through a single shared `DataField#numeric_or_nil` helper so they can't drift.
-2. **Created CANS pages** unsubmitted (first stage): parked — out of scope for now (Oscar).
-3. **TOOCS stage**: confirm `6a3225522b97b00073c22d7d` is the 'Coding' stage in act-gov (the
-   model dump tool can verify against the live page). Non-blocking.
-
-## Tooling delivered
-- `tests/dump_page_model.rb` — pulls a page's GraphQL model (CommonPageUnion doc) to JSON,
-  before/after a submit, for capturing real fixtures + diffing what a submit changed.
-- `spec/fixtures/pages/toocs_coding_page.json` — TOOCS page fixture (observed ids).
-- `spec/ecoportal/api/graphql/integration/toocs_submit_replay_spec.rb` — replays the case flow,
-  asserts the EXACT observed body, and proves the regression (stageless submit raises; stage view
-  resolves it).