ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/projects/graphql-agent/GAP_ANALYSIS.md

@@ -1,177 +0,0 @@
-# GraphQL Agent Corpus — Gap Analysis
-
-*Analysed 2026-06-07 from staging corpus at `C:\claude\Projects\Claude AWS Platform\tmp\corpus\staging\success\graphql\`*
-*18 staging documents reviewed.*
-
----
-
-## Critical — Breaks Agent Reliability
-
-| File | Issue | Fix |
-|------|-------|-----|
-| `2262499334_search-by-external-id.md` | Contains placeholders (`"graphqlwide760"`, `"jsonwide760"`) instead of actual query/variables | Replace with real contractor search examples |
-| `2262892608_registers-searches-and-templates.md` | Entirely empty after header — no content | Populate register structure, preset views, search config |
-| Agent instructions (absent) | No guidance that GraphQL queries are client-defined — agent will expect structural uniformity | Add "GraphQL is a Language" note (see below) |
-
----
-
-## High — Agent Will Hallucinate Without Guidance
-
-### Error handling — completely missing
-No error taxonomy. No error codes. No recovery patterns. The agent will invent error names
-and suggest incorrect recovery steps.
-- **Add:** 20–30 common error codes with cause and recovery (e.g. `patchVer` conflict,
-  invalid field ID, permission denied, stale cursor)
-
-### State machines — completely missing
-No documented states for Page, Stage, Action, Task. No valid transitions. Agent will
-suggest invalid state changes.
-- **Add:** State diagrams or transition tables for each entity
-
-### Authorization — completely missing
-`canXXX` fields exist on every Page, Stage, Action. What they mean is never explained.
-- **Add:** `canXXX` field guide — when they return false, what the caller should do
-
-### Filter syntax — incomplete and inaccurate
-The search filter docs show `fieldName` in examples but production queries use `key`.
-Filter operation names are snake_case (silent failure if CamelCase is used — no error,
-no results). `filters` should always be an Array.
-- **Add:** Complete filter operation reference with snake_case requirement explicit.
-  See `.ai-assistance/code/search_filters.md` in `ecoportal-api-graphql`.
-
-### Field ID lifecycle — missing
-Docs warn that field IDs change between template and instance, but give no algorithm for
-resolving them (when to `buildFromTemplate` first, when to look up by type+label, etc.)
-- **Add:** "Field ID Resolution" section — the two-step workflow and when each applies
-
-### `updateMode` on actions — undocumented
-The UpdateAction mutation accepts `updateMode` but valid values are not documented.
-Agent will omit or guess (single / series / future / all).
-- **Add:** `updateMode` enum values with examples
-
----
-
-## Medium — Gaps That Reduce Usefulness
-
-### Covered but incomplete
-
-**Pages technical guide (`2235662347`):**
-- Missing: how `showHiddenData` interacts with field visibility
-- Missing: page state vs. stage state distinction
-- Missing: what `templatesOnly` does (returns templates as pages, not instances)
-- Missing: partial update semantics (sparse fields vs. full replacement)
-
-**Authentication (`1959788614`):**
-- `scope` shown as `[]` with no explanation
-- Token expiry and refresh failure handling missing
-- Security best practices for token storage missing
-
-**Searching pages (`1933639695`):**
-- Only 3 filter examples — no matrix of all filterable fields
-- No field-value filters (search by a specific data field value)
-- `mould_counter` appears in example with no explanation (deprecated; use `uid`)
-
-**Load actions (`1933901853`):**
-- Uses both `edges { node { ... } }` and `nodes` inconsistently
-- `Search` input type not documented alongside its usage
-
-**Create/Update page mutations:**
-- No guidance on transaction semantics (is a partial dataFields update atomic?)
-- Missing: what happens if one field update fails — does the mutation continue or abort?
-
-### Not covered at all
-
-- Contractor entity lifecycle (create / approve / activate / archive)
-- Archive and unarchive page flows (compound mutation pattern)
-- File upload mechanics (separate from attach)
-- Bulk/batch operations
-- Visitor management integration
-- Page forces / risk management
-- Task workflow and status transitions
-- AI Summary field operations
-- Mailbox field operations
-- Cross-reference field deep guidance
-- People field — `cachedPeople` vs. `livePeople` distinction
-- Webhook / subscription patterns
-- Rate limiting and throttling
-- Cursor invalidation policy (how long cursors remain valid)
-- `deindex` and field visibility flags semantics
-
----
-
-## Accuracy Concerns
-
-| File | Issue |
-|------|-------|
-| `1931575325_updatepage.md` | Example variables may reference `templateId` where `id` (page ID) is expected |
-| `1928855618_createaction.md` | Response structure example (`item: { ... }`) may not match actual wrapper |
-| `2235662347_graphql-pages-technical-guide.md` | Refers to `pageUnionCommonFragment` but fragment definition is in a separate doc with no cross-link |
-| Multiple | Date formats mixed (ISO8601 with Z vs. with +offset) — no guidance on when each is correct |
-| Multiple | Broken Confluence external links (opaque IDs, unresolvable outside Confluence) |
-
----
-
-## Structural Issues
-
-1. **No agent preamble.** There is no document that tells the agent the most important
-   invariants: GraphQL variability, silent filter failures, two-step field ID resolution,
-   compound mutation pattern. These must be added as explicit agent instructions, not
-   buried in examples.
-
-2. **No cross-reference index.** `CommonPageUnion` is referenced in 6+ documents but
-   defined in only one. An agent cannot reliably find what it needs.
-
-3. **No versioning or timestamps.** The agent cannot tell if a doc reflects the current
-   schema or an old version. Schema changes may invalidate examples silently.
-
-4. **Inconsistent example depth.** Some mutations show full request + response; others
-   only show the query. Agent will fill in gaps incorrectly.
-
-5. **Fragment defined but not explained.** `CommonPageUnion` shows the full GraphQL but
-   nowhere explains what `$content`, `$only_content`, `$fields` actually control in
-   human terms (with examples of before/after).
-
----
-
-## Recommended Agent Preamble (add to system prompt or corpus index)
-
-```
-You are assisting with the EcoPortal GraphQL API. Key invariants:
-
-1. GraphQL queries are client-defined. The same resource can be queried many ways.
-   Variability in examples is intentional. Multiple mutations in one request (executed
-   in order) is valid and used for stateless middleware clients.
-
-2. Filter operations are snake_case strings. CamelCase silently returns no results.
-   Always use: exact_filter, date_filter, and_filter, or_filter, register_filter.
-   The `filters` value should always be an Array.
-
-3. Page creation requires a 2-step sequence:
-   (a) buildFromTemplate → get field IDs from the built draft
-   (b) createFromTemplate → use those field IDs in dataFields.updates
-
-4. Page update requires:
-   (a) Fetch current page → get patchVer + current field IDs
-   (b) updatePage → include patchVer (required for concurrency control)
-
-5. The CommonPageUnion fragment ($fields/$content/$only_content variables) is the
-   standard pattern for fetching full page data. Use it for all page read operations.
-
-6. Register search (previewPages) is Elasticsearch — fast but no field IDs.
-   Org search (pages) is DB — slow (~3s/page) but complete data including field IDs.
-```
-
----
-
-## Recommended Additions Priority
-
-1. Error taxonomy (codes, causes, recovery)
-2. State machines (Page, Stage, Action, Task)
-3. Field type matrix (all 20 types, validation, modifiers)
-4. Full contractor management (currently broken/empty)
-5. Authorization guide (`canXXX` meanings)
-6. Archive/unarchive patterns
-7. File upload guide
-8. Complete filter fieldName reference
-9. `updateMode` enum for actions
-10. Cursor invalidation policy

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

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

@@ -1,125 +0,0 @@
-# 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/INVENTORY.md

@@ -1,136 +0,0 @@
-# INVENTORY — Ooze → Native GraphQL Migration (Phase 0)
-
-Verified 2026-07-02 against actual code in `eco-helpers` (main code), `ecoportal-api-graphql`
-(gem), and `implementation/training` (downstream consumers). This is the **master schedule
-partition**: which cases can migrate now vs. are blocked on forces, and the BC surface that must
-keep working with **zero customer-script edits**.
-
-> **Scope note (Oscar, 2026-07-02):** this project currently builds the **native GraphQL classes
-> only**. We do NOT yet flip the `OozeSamples::*` names to delegate, and we do NOT remove shim
-> code. The delegation flip happens "long after we know everything works on the native samples."
-
----
-
-## A. The ooze case inheritance tree (eco-helpers)
-
-Root path: `lib/eco/api/usecases/ooze_samples/`
-
-```
-Eco::API::Common::Loaders::UseCase
-├─ OozeSamples::OozeBaseCase                       (ooze_base_case.rb)  include Helpers, Helpers::Rescuable
-│   └─ OozeSamples::OozeRunBaseCase                (ooze_run_base_case.rb)  single-ooze runner
-│       └─ OozeSamples::OozeUpdateCase             (ooze_update_case.rb)
-│           └─ OozeSamples::OozeFromDocCase        (ooze_from_doc_case.rb)  + Word-doc parsing
-│   └─ OozeSamples::RegisterUpdateCase             (register_update_case.rb)  include Helpers::Creatable   ← CUTOVER #1
-│       └─ OozeSamples::TargetOozesUpdateCase      (target_oozes_update_case.rb)  CSV target ids           ← CUTOVER #2
-│       └─ OozeSamples::RegisterMigrationCase      (register_migration_case.rb)  include HelpersMigration
-└─ OozeSamples::RegisterExportCase                 (register_export_case.rb)  standalone (NOT under OozeBaseCase)
-    └─ OozeCases::ExportRegisterCase               (ooze_cases/export_register_case.rb)  include ExportableRegister
-```
-
-### Control-flow loop a native class must reproduce (RegisterUpdateCase)
-
-- `main(session, options, usecase, mode: :legacy)` → init KPIs → `:legacy` runs
-  `with_each_entry { process_ooze(&block) }`; `:delegate` yields for a custom loop → log KPIs.
-- `with_each_entry` → `batched_search_results` yields page batches → per page: dedup check →
-  `ooze(id)` load → yield to block → `update_oozes` (batch save).
-- `batched_search_results` → `apiv2.registers.search(register_id, search_options) { ... }`,
-  batch-size chunking.
-- `search_options` → sort=created_at asc, `conf_search` (→ `search` hook), `conf_filters`
-  (→ `filters` hook).
-- KPI counters: `total_search_oozes`, `retrieved_oozes`, `dupped_search_oozes`, `updated_oozes`,
-  `failed_update_oozes`, `created_oozes`, `ooze_create_attempts`.
-- Dry-run: `results_preview` (confirm total, 10s timeout); `display_patch` / `backup_patch!` in base.
-- Internal batch queue: `enqueue` / `queue_shift` / `queue_get` (duck-types v2 Page / PageStage /
-  anything responding to `dirty?` + `as_update`).
-
-`TargetOozesUpdateCase` overrides only `with_each_entry` (reads target ids from CSV column 1+,
-batches by size) — everything else inherited.
-
-**Native counterpart already has a head start:** eco-helpers
-`lib/eco/api/usecases/graphql/samples/pages/page/base.rb` already implements a **native GraphQL
-loop** (`process` → `init_kpis` → `each_page` → `process_page` → `log_kpis`, plus `update_page`
-with a simulate guard and register-scoped `search_conf`). The native register case builds on this
-`Pages::Page::Base`, NOT on a v2 loop.
-
----
-
-## B. Helper modules — v2-coupled vs pure
-
-Root: `lib/eco/api/usecases/ooze_samples/helpers/` and `helpers_migration/`
-
-| Module | Path | Classification | Migration action |
-|---|---|---|---|
-| `Helpers::Shortcuts` | helpers/shortcuts.rb | **PURE** (string simplify/compare; one `obj.force` in a message) | Port ~verbatim to `graphql/helpers/pages/` |
-| `Helpers::Filters` | helpers/filters.rb | **PURE** (tag/date filters, time math) | Port ~verbatim |
-| `Helpers::Rescuable` | helpers/rescuable.rb | error-rescue wrapper | Port (thin) |
-| `Helpers::Creatable` | helpers/creatable.rb | **v2-coupled** (`apiv2.pages.get_new/create`; duck-types v2 Page) | GraphQL re-expression (native draft + create) |
-| `Helpers::OozeHandlers` | helpers/ooze_handlers.rb | **v2-coupled** (`merge_values` case-matches `V2::Page::Component::*`) | GraphQL-typed re-expression (per data-field type) |
-| `Helpers::ExportableOoze` | helpers/exportable_ooze.rb | v2-coupled (field value reads) | later (export cases) |
-| `Helpers::ExportableRegister` | helpers/exportable_register.rb | v2-coupled (ooze value aggregation) | later (export cases) |
-| `HelpersMigration::Copying` | helpers_migration/copying.rb | **v2-coupled** (field pairing/copy) | later (migration case) |
-| `HelpersMigration::TypedFieldsPairing` | helpers_migration/typed_fields_pairing.rb | **v2-coupled** (type+label pairing) | later (migration case) |
-
-**First-wave port:** `Shortcuts`, `Filters`, `Rescuable` (pure/thin) + a native `Creatable`.
-
----
-
-## C. The compat shim being retired (NOT this session)
-
-`lib/eco/api/usecases/graphql/compat/ooze_redirect.rb` (+ `ooze_redirect/{dirty_array,field_patches,force_compat}.rb`).
-
-- `OozeRedirect.included(base)` → `FieldPatches.apply!` (global v2-class reopening + GraphQL field
-  prepends), `base.include(GraphQLEnv)`, `base.prepend(Infrastructure)`,
-  `+ ForceCompat::Infrastructure if force_support?` (currently `false`).
-- `Infrastructure` overrides (the leaf ops a native class implements directly instead):
-  `api_v2`/`apiv2` → `graphql`; `stage(name)` → `StageView`; `with_fields(ooz, type:, label:)` →
-  reads `ooz.components`; `dirty?` → `.dirty?` or captured submit/sign-off flags.
-- `FieldPatches` steps: v2 `===` dispatch lie; GraphQL BasePage `submit!`/`sign_off!` + pending
-  flags; People `DirtyArray`; CrossReference `reference_ids`/`add`/`clear`; Select
-  `options`/`select`/`deselect`/`values`.
-
-A native class needs NONE of these patches — it dispatches on GraphQL types directly.
-
----
-
-## D. Forces partition (blocked until GraphQL forces endpoint is live)
-
-- **Base ooze cases (A) do NOT use forces** — `OozeBaseCase`, `RegisterUpdateCase`,
-  `TargetOozesUpdateCase`, `RegisterMigrationCase`, `RegisterExportCase` are all force-free.
-  → **All first-wave cutover cases are migratable now.**
-- **Forces live only in downstream training scripts** that subclass the register cases:
-  | Script | Base | Force usage |
-  |---|---|---|
-  | `les_mills_force_update_case.rb` (Test_Les) | RegisterUpdateCase | `forces.get_by_name` → `force.custom_script =` |
-  | `20231031_fix_options_case.rb` (FIXOPTIONS) | RegisterUpdateCase | `forces.each` → `force.custom_script =` |
-  | `08102024_THL_RemoveLocTitle_case.rb` (REMOVELOCTITLEHAZ) | RegisterUpdateCase | `forces.get_by_name` → `custom_script =` |
-  | `rename_field_case.rb` (AddFieldBinding) | RegisterUpdateCase | `forces.delete!` |
-  | `attach_image_case.rb` (AttachImage) | TargetOozesUpdateCase | `forces.get_by_name` |
-- **Note:** the gem *does* ship forces write commands via the command bus
-  (`addForce`/`editForce`/`addBinding`/…) and `OozeRedirect.force_support?` being `false` is
-  stale/conservative (see memory `forces-via-workflow-commands`). But the ooze-case force *read*
-  path (`target.forces.get_by_name`, `force.custom_script=`) is a different surface and its
-  GraphQL end-to-end readiness is UNCONFIRMED. These scripts stay on the v2 path until confirmed.
-
----
-
-## E. Downstream include-site inventory (BC surface)
-
-- Training repo `C:\ruby_scripts\implementation\training` **exists**; **273+ custom cases**.
-- **All are still APIv2-only** — none currently `include GraphQL::Compat::OozeRedirect` (the live
-  TOOCS/CANS cutover scripts that DO use it are not in this training tree — locate them before any
-  flip; not needed this session since we are not flipping).
-- Overrides seen across consumers (the hooks a native class must keep honoring):
-  `process_ooze` (always), `search`, `filters`, `custom_processing`, plus script-local helpers
-  (`with_target_stage`, `target_stage`, `with_target_field`, `with_target_force`, etc.).
-
----
-
-## F. Migration order (schedule)
-
-1. **Now (native only):** port pure helpers (`Shortcuts`, `Filters`, `Rescuable`) + native
-   `Creatable`; native register base case on top of `Pages::Page::Base`; specs. **No flip.**
-2. Native `RegisterUpdateCase` + `TargetOozesUpdateCase` counterparts; A/B parity harness.
-3. (Later) flip old names → delegate, per-case, parity-gated; remove shim slices.
-4. (Blocked) force-using cases — pending GraphQL force read/write end-to-end confirmation.
-5. (Later) export + migration cases (`ExportableRegister`, `Copying`, `TypedFieldsPairing`).