ecoportal-api-graphql 1.3.5 → 1.3.9

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

@@ -0,0 +1,256 @@
+# 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.**
+
+---
+
+## Phase 0 — Inventory & Baseline (no code changes)
+
+### 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

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

data/.ai-assistance/projects/ooze-graphql-native-migration/analysis/2026-07-01-forces-via-workflow-commands-miss-rca.md

@@ -0,0 +1,148 @@
+# RCA — "Forces are blocked on GraphQL" was wrong: forces are mutable via the Workflow* command-bus
+
+**Date:** 2026-07-01
+**Author:** retrospective analysis (AI agent), reviewed-by: pending (Oscar)
+**Scope:** Why a clarified platform fact — *forces are created/edited/removed on GraphQL via `Workflow*` command types through `executeWorkflowCommands`* — was repeatedly missed, leaving a stale "blocked on forces" narrative in `eco-helpers` that disabled ~50% of ooze cases.
+**Constraint:** analysis + recommendations only. No source code was changed.
+
+---
+
+## 1. Executive summary
+
+**What was missed.** ecoPortal FORCES are fully mutable on GraphQL through the `WorkflowCommandInput` command-bus — `addForce` / `editForce` / `removeForce` / `reorderForces` / `addBinding` / `editBinding` / `removeBinding` — applied via the `executeWorkflowCommands` mutation. The gem has shipped these command inputs **and** the mutation client since 2026-06-10/11. There is **no** separate "forces endpoint" and there never needed to be one for *writes*.
+
+**The one-line root cause.** The `OozeRedirect.force_support?` readiness gate keyed on the wrong signal — the presence of a **broken READ query** (`Query::PageWithForces`) — and when that signal flipped true it routed *every* ooze case through the broken read. The fix was to hard-disable the gate (`force_support? => false`), which threw out the **working MUTATE path** as collateral and froze a comment that over-generalises "the broken read" into "forces are NOT usable on GraphQL." The READ-vs-MUTATE distinction was never made explicit at the gate, so a read-only defect masqueraded as a total-capability block.
+
+**Net effect.** `ooze_redirect.rb` simultaneously (a) ships a `ForceCompat` that *correctly* drives writes through `executeWorkflowCommands`, and (b) asserts in prose that "Forces are NOT usable on GraphQL yet … blocked on GraphQL endpoint," listing ~50% of ooze cases as blocked. The codebase contradicts itself.
+
+---
+
+## 2. The contradiction, with file:line evidence
+
+### Side A — "forces are blocked" (eco-helpers)
+
+`C:\ruby_scripts\git\eco-helpers\lib\eco\api\usecases\graphql\compat\ooze_redirect.rb`
+
+- **L42-49** — `## Limitations`: "Force / binding operations (`target.forces`, `force.bindings`) are not available in GraphQL — those calls will raise NoMethodError."
+- **L51-77** — `## TODO: Force / binding support (blocked on GraphQL endpoint)`: "Engineering is working on exposing 'legacy forces' via the GraphQL API. Once that endpoint is available, extend this module with a `ForceCompat` sub-module …" — followed by a v2-shaped API sketch (`target.forces.get_by_name`, `force.bindings.add`, `force.custom_script = new_script`) and a roster of ~22 named cases across 10 orgs declared "currently blocked … ~50% of all ooze cases."
+- **L113-122** — `force_support?`:
+  ```ruby
+  # Forces are NOT usable on GraphQL yet: Query::PageWithForces is a WIP whose query
+  # currently fails schema validation … and the backend forces endpoint is still in
+  # progress. … Keep OFF until forces actually work …
+  def self.force_support?
+    false
+  end
+  ```
+
+### Side B — "forces are mutable, right now" (the gem, already shipping)
+
+- `lib\ecoportal\api\graphql\input\workflow_command.rb` **L106-117** — the `# Forces` block of `COMMAND_MAP` wires `addForce`, `removeForce`, `editForce`, `reorderForces`, `addBinding`, `editBinding`, `removeBinding` (+ `addLinkedHelper`/`editLinkedHelper`/`removeLinkedHelper`). These are first-class members of the command-bus, on the same footing as `addStage`, `addField`, etc.
+- `lib\ecoportal\api\graphql\input\workflow_command\add_force.rb` — `VALID_KEYS = %i[placeholderId name customScript url contentB64]`, `SCHEMA_VERSION '20260605'`.
+- `…\edit_force.rb` — `VALID_KEYS = %i[id name customScript url contentB64]`.
+- `…\add_binding.rb` — `VALID_KEYS = %i[placeholderId forceId name referenceId type]`.
+- `lib\ecoportal\api\graphql\mutation\page\execute_workflow_commands.rb` — `field_name :executeWorkflowCommands`; the generic command applier (`mutation(... commands: :WorkflowCommandInput!)`).
+- `lib\ecoportal\api\graphql\mutation\page\execute_force_commands.rb` **L26-37** — `ExecuteForceCommands` is now a thin `@deprecated` alias that *delegates to the same `executeWorkflowCommands` mutation*. Its own doc-comment (L20-25) shows `{ editForce: {...} }`, `{ addBinding: {...} }`, `{ removeBinding: {...} }`, `{ removeForce: {...} }` as the command payloads.
+- `lib\ecoportal\api\graphql\base\force.rb` **L33-60** — `Base::Force#custom_script=` queues `editForce`; `#all_pending_commands` emits `{ editForce: { id:, customScript: } }`; bindings queue `addBinding`/`removeBinding`. The write model is complete and unit-shaped.
+
+### Side C — the smoking gun: the "v2-style" sketch is already the command-bus
+
+The "to be built when the endpoint lands" sketch in `ooze_redirect.rb` (L79-89) describes exactly what the **already-shipped** `force_compat.rb` does — and that file does **not** call any forces endpoint:
+
+`C:\ruby_scripts\git\eco-helpers\lib\eco\api\usecases\graphql\compat\ooze_redirect\force_compat.rb`
+- **L43-46, L62-66** — `process_ooze` → `save_force_changes!` → `graphql.page.execute_force_commands(id:, patch_ver:, commands:)`, i.e. it submits `force_col.pending_commands` **through `executeWorkflowCommands`**. The write half was *finished* the same day the TODO was written.
+
+So the prose ("blocked on endpoint," "to be built") and the code ("here is the working write path through the command-bus") are in direct contradiction *within the same module*.
+
+---
+
+## 3. The read-vs-mutate conflation (the conceptual core)
+
+Two genuinely distinct concerns were collapsed into one boolean:
+
+| Concern | Mechanism | Status (as of 2026-06-30) |
+|---|---|---|
+| **(a) READ legacy forces on a page** | `Query::PageWithForces` — selects `forces { ...ForceFields }` on the page union | **WIP / broken**: per commit `de62d2d1`, the query "fails schema validation (PageUnion selections; `id` on DataFieldBinding/SectionBinding; unused ForceFields)." This is a *client query shape* defect. |
+| **(b) MUTATE forces** | `executeWorkflowCommands(commands: [WorkflowCommandInput])` with `editForce`/`addBinding`/`removeForce`/… | **Working / shipped** since 2026-06-10 (`cd57b54`) and folded into the unified command-bus 2026-06-11 (`8e8f492`). |
+
+The v2 mental model treats a force as a *page sub-object you read, then mutate in place*: `page.forces.get_by_name(...)`, `force.bindings.add(...)`, `force.custom_script = ...`, with a LISP `custom_script` you edit. In that model, reading and writing are the **same** object graph, so "I can't read forces" naturally implies "I can't do forces."
+
+The new platform model is **imperative**: you don't read-then-mutate a live object; you *emit commands* (`editForce { id, customScript }`, `addBinding { forceId, ... }`) into `executeWorkflowCommands`, exactly like every other template/workflow change. In this model, **read and write are decoupled** — a write needs only the force/binding `id` and the new value; it does **not** require `PageWithForces` to be schema-valid.
+
+**The conflation:** because the gate (`force_support?`) was attached to the *read* query, and because `force_compat.rb` *also* uses `PageWithForces` to fetch (`with_each_entry`, L30-40), the broken read poisoned the whole feature. The "blocked" conclusion was drawn from the broken READ query and then **over-generalised to ALL force operations** — including the writes that already worked. The v2 carryover (looking for a forces *endpoint*, i.e. a place to read forces from) is precisely what made the read query feel like the readiness signal.
+
+---
+
+## 4. Git timeline — what existed when
+
+**Gem (`ecoportal-api-graphql`):**
+
+| Date | Commit | Event |
+|---|---|---|
+| 2026-06-10 | `cd57b54` | `feat: Force model + fragment + mutation + query for ForceCompat support` — adds `Base::Force` (+ bindings, collection, `custom_script=` queues `editForce`), `Fragment::ForceFields`, **`Mutation::Page::ExecuteForceCommands` (write)** AND **`Query::PageWithForces` (read)** together. Writes were present from day one. |
+| 2026-06-11 | `8e8f492` | `feat: expose PagesWorkflow space (W1-W5) — read models, command bus, fragments, specs, docs` — adds the full `WorkflowCommand` command-bus incl. `add_force/edit_force/remove_force/reorder_forces/add_binding/edit_binding/remove_binding`; `ExecuteForceCommands` becomes a deprecated delegator to `executeWorkflowCommands`. |
+| 2026-06-16 | `bafbf80` | `fix: require all field_config byType modules in WorkflowCommand`. |
+
+**eco-helpers (`ooze_redirect.rb` / `force_compat.rb`):**
+
+| Date | Commit | Event |
+|---|---|---|
+| 2026-06-09 | `457eccd9` | `feat: GraphQL::Compat::OozeRedirect` — shim created. |
+| 2026-06-09 | `244aff8a` | `docs: OozeRedirect Forces TODO block` — **the "blocked on GraphQL endpoint" prose written BEFORE the write path shipped.** At this moment the claim was *defensible*. |
+| 2026-06-10 | `e3bc7f0a` | `feat: OozeRedirect::ForceCompat — force/binding support via GraphQL` — the working write path lands (`save_force_changes!` → `execute_force_commands`). **The TODO prose was now stale but was not removed.** |
+| 2026-06-30 | `de62d2d1` | `fix(ooze-redirect): disable ForceCompat (forces WIP)` — `force_support?` was `defined?(Query::PageWithForces)`; once the gem force-loaded that became `true`, prepending `ForceCompat` for *every* case and routing `with_each_entry` through the broken read. Hard-disabled to `false`. **This correctly stopped the broken read from breaking toocs/cans — but the accompanying comment re-asserted the over-general "forces are NOT usable" claim, re-freezing the stale narrative instead of narrowing it to the read query.** |
+| 2026-06-30 | `d12f5552` | `fix(ooze-redirect): faithful dry-run + slim shim` — current state. |
+
+**Key finding:** the write command inputs existed (2026-06-10/11) *before* the "blocked" claim was last reinforced (2026-06-30). The reinforcement on 2026-06-30 had the gem's working force-write code sitting in the same dependency tree — yet the comment still said "blocked on GraphQL endpoint." The DECISIONS log entry of the **same day** (`[2026-06-30] Forces-dependent cases are HELD pending a Phase 0 live readiness test`, `ooze-graphql-native-migration/DECISIONS.md` L120-148) *did* finally record the correction ("the GraphQL force endpoint is NOT read-only or missing — the gem ships both … read AND … write"). So the correction landed in the **project decision log** but did **not** propagate back into the `ooze_redirect.rb` gate/comment that consumers and future agents actually read.
+
+---
+
+## 5. Root-cause chain (ranked)
+
+1. **Wrong readiness signal + read/write coupling (primary).** `force_support?` keyed on `defined?(Query::PageWithForces)` — a *read* class — as a proxy for "forces work." Because `force_compat.rb#with_each_entry` *fetches* via `PageWithForces`, the broken read could break unrelated cases, forcing a binary all-off switch. A capability that is two independent halves (read vs write) was gated by one boolean tied to the broken half. The write half was never given its own gate, so it died with the read.
+
+2. **Stale doc never re-examined after the feature shipped (close second).** The "blocked on endpoint" TODO was written 2026-06-09 (`244aff8a`) when it was *true*, then the write path shipped 2026-06-10 (`e3bc7f0a`) **in the same module**, and the TODO was never reconciled. Doc rot: the prose became a fossil that subsequent edits (incl. 2026-06-30) treated as ground truth and even *expanded* rather than questioned.
+
+3. **Verified platform fact lived only in machine-local memory, invisible across sessions/agents (structural).** The general command-bus architecture ("templates updated imperatively via ~80 `WorkflowCommandInput` types") was captured in `project_template_update_architecture.md` and `project_workflow_space.md` under `C:\Users\rella\.claude\projects\…\memory\` — a **per-machine, gitignored** store. That store is invisible to (a) other machines, (b) other agents/sessions, (c) anyone reading the repo. The fact was "known" in one silo but had no **code-adjacent, shared** form, so it could not contradict the stale comment at the point of use.
+
+4. **The captured general fact was never specialised to the force inference (reasoning gap).** Even where the command-bus was known, nobody made the *specific* deduction: "forces are members of the command-bus → forces are mutable on GraphQL → `force_support?` must not be hard-false for writes." The general → specific link was never drawn. Knowing "templates are updated via commands" did not automatically surface "therefore the forces-blocked claim is wrong," because forces were mentally filed under "legacy read object," not "command-bus member."
+
+5. **v2 endpoint mental model (contributing).** The team looked for a forces *endpoint* (a place to read/CRUD forces as objects) rather than recognising forces as just-another-command in an existing imperative bus. This is why the read query felt load-bearing and why the TODO sketch reinvented a v2-shaped `forces.get_by_name/.bindings.add` API that the command-bus had already obviated for writes.
+
+---
+
+## 6. Concrete corrections
+
+### (a) `ooze_redirect.rb` — gate + comment (DESCRIBE; not applied)
+
+- **Split the capability into READ vs WRITE.** Do not let a single `force_support?` boolean conflate them.
+  - **Writes** (`editForce`/`addBinding`/`removeBinding`/`removeForce` via `executeWorkflowCommands`) are available **now** and do not depend on `PageWithForces`. The write path in `force_compat.rb#save_force_changes!` is correct as written.
+  - **Reads** (`Query::PageWithForces`) are the only WIP part. The blocker is a *client query-shape* bug (PageUnion selection set; `id` on `DataFieldBinding`/`SectionBinding`; unused `ForceFields`), not a missing backend endpoint.
+- **Re-scope the gate.** Replace the hard `false` with a gate that reflects the real dependency: ForceCompat's *fetch* (`with_each_entry` via `PageWithForces`) is what must be gated, not force mutation per se. Options:
+  - Gate ForceCompat activation on a **read-readiness** check (only prepend `ForceCompat::Infrastructure` when `PageWithForces` is schema-valid against the live org), so toocs/cans never route through the broken read; **or**
+  - Decouple the fetch from the mutate: let ForceCompat reuse the *standard* page fetch and only add the write-command accumulation, fetching forces via a separate call (or a fixed `PageWithForces`) only for cases that actually touch forces. This lets writes proceed even while the read query is being fixed.
+- **Rewrite the prose (L42-89, L113-122).** Delete "Force / binding operations are not available in GraphQL" and "blocked on GraphQL endpoint." Replace with the accurate split: "Force/binding **writes** are available now via `executeWorkflowCommands` (`editForce`/`addBinding`/`removeBinding`/`removeForce`). The only WIP is **reading** existing forces on a page (`Query::PageWithForces` fails schema validation — fix the selection set). The ~50% 'blocked' roster is **not** blocked on a missing endpoint; it is at most blocked on the read query for cases that must *inspect* current forces before mutating." Keep the case roster but relabel it "force-touching cases (verify read-vs-write need per case)."
+- **Cross-link** the comment to the DECISIONS entry (`ooze-graphql-native-migration/DECISIONS.md` L120-148) so the gate and the decision log can't drift apart again.
+
+### (b) verified-platform-knowledge entry to capture
+
+Create a durable, **repo-committed** platform-fact entry (not machine-local memory):
+
+> **Forces on GraphQL are mutated via the `WorkflowCommandInput` command-bus, applied with the `executeWorkflowCommands` mutation.** Command keys: `addForce`, `editForce`, `removeForce`, `reorderForces`, `addBinding`, `editBinding`, `removeBinding` (gem: `Input::WorkflowCommand::*`, `COMMAND_MAP` L106-117). There is **no** separate forces write endpoint. A force `editForce` needs only `{ id, customScript }`; a binding needs `{ forceId, name, referenceId, type }`. Confirmed by Oscar (more than once) and by shipped gem code (`cd57b54` 2026-06-10, `8e8f492` 2026-06-11).
+> **Only WIP part:** *reading* existing forces on a page via `Query::PageWithForces` — currently fails client-side schema validation (PageUnion selection set; `id` on `DataFieldBinding`/`SectionBinding`). This is a query-shape fix, not a backend gap.
+> **Anti-pattern to retire:** the v2 "forces endpoint / `page.forces` live object" mental model. Forces are command-bus members, not a CRUD endpoint.
+
+Suggested home: a committed `verified-platform-knowledge` doc (e.g. under `.ai-assistance/code/` or a `.ai-assistance/local/standards-requests/` entry that gets promoted to a shared, committed location — note: `.ai-assistance/local/standards-requests/` does **not currently exist** in this repo, see §7).
+
+### (c) process fix to prevent recurrence
+
+1. **Promote verified platform facts out of machine-local memory into committed, code-adjacent docs.** The command-bus fact lived only in `~/.claude/.../memory/` (gitignored, per-machine). A platform fact that gates real code MUST be captured where every agent/session/teammate and the code reviewer can see it — i.e. committed to the repo near the code it governs. This is the textbook case the `verified-platform-knowledge` standards request is meant to solve: a user-clarified fact that never became durable shared knowledge, so a stale "blocked" assertion survived and was reinforced.
+2. **Doc-and-gate co-location invariant.** When a feature ships its write path (commit `e3bc7f0a`), any "TODO/blocked" prose describing that feature in the *same module* must be reconciled in the same change. A lint/check or a PR-checklist item: "Did this commit make any nearby 'blocked/TODO/not available' comment stale?"
+3. **Never gate a multi-part capability on a single boolean tied to one part.** Capability gates should name the *specific* dependency (here: "ForceCompat fetch needs a schema-valid `PageWithForces`"), not a coarse "forces work." A gate comment should be falsifiable and cite the exact failing artifact.
+4. **Close the loop from DECISIONS log back to code.** The 2026-06-30 DECISIONS entry recorded the correct fact but the `ooze_redirect.rb` gate/comment was not updated to match. Decision-log entries that contradict a code comment should spawn a tracked task to fix the comment, or the decision isn't "done."
+
+---
+
+## 7. Note on the standards mechanism
+
+The task referenced `.ai-assistance/local/standards-requests/` (a `verified-platform-knowledge` request). **That directory does not exist in this repo as of 2026-07-01** (`.ai-assistance/local/` was not present). This RCA is therefore a concrete, documented justification for creating that mechanism: a verified platform fact (forces = `Workflow*` command-bus), clarified by the maintainer more than once, was never captured as durable, shared, **committed** knowledge — so a stale "blocked on endpoint" assertion persisted across three weeks and was actively reinforced even after the contradicting code shipped in the same module. A committed verified-platform-knowledge store, co-located with the gated code and cross-linked from the DECISIONS log, would have surfaced the contradiction at the gate.