eco-helpers 3.2.14 → 3.2.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d67a16095de2e32c2c627214b0254df6d2685e0591ab6295082736e52494c4d3
-  data.tar.gz: 60835a688189d8feda9bdc6198bbdb0cfaa9e9f95e5c7521f36cedbec706c1b0
+  metadata.gz: 2f79a58827dc2789ddfcc56e108d93520af92c15152b94338ca51e73cc388210
+  data.tar.gz: e15e69fdb8fa6bd37202aad7f01bebcda80c9aadacc23333a98846a27aeddffd
 SHA512:
-  metadata.gz: 0c1ded6a88ad0c6394e96cb511fddb5c5ac29635307affc1577d5eeb210f01ad8dd78edf78e449b9bca765a8754aa31083abb72beb60746ed21741e523878e6c
-  data.tar.gz: a18f9c81c2430ba8251bdfc34e6e4e1d3da0fd3cbe4647226942469d8da1f71e00aa7e21e3162d9d89d492f98e800642c0132edc30a305515df67764c397de91
+  metadata.gz: 14faa786d74eb1b096cea772f79903df7f16e0dd903ce8586621f4524413795f0720bad631b0ddbc892cee01d12e6445f2af5ff6ff808d5754bb8593959f5d9a
+  data.tar.gz: b8b28cba91173036b005e3aa9a8e88e0143a932e1342c4aa91f085c73d4e031191e5f09c8f71928547392e41291c8b0128d0455b1b646ab93422247b9cac57b9

data/CHANGELOG.md

@@ -2,6 +2,213 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.2.22] - 2026-08-14
+
+### Fixed
+
+- Republish of `3.2.21`: its `lib/eco/version.rb` shipped with doubled carriage returns
+  (`
+` line endings), causing a `warning: encountered 
 in middle of line` on every
+  load. Functionally identical otherwise; `3.2.21` will be yanked.
+
+## [3.2.21] - 2026-08-14
+
+### Fixed
+
+- Packaging-only republish of `3.2.19` with an allowlisted gemspec (backported from `3.3.0`).
+  Versions `3.2.16`-`3.2.19` shipped internal repository content (`.ai-assistance/` tooling,
+  `.claude/settings.json`) to rubygems.org via the old denylist `spec.files`; `3.2.19` is
+  yanked and `3.2.16`/`3.2.18` are queued for deletion by RubyGems support. `3.2.21` is the
+  identical `lib/` code packaged clean, so constraints like `'~> 3.2.0', '>= 3.2.19'` keep
+  resolving on the 3.2 line (its graphql dependency stays `~> 1.3`, satisfied by the clean
+  `1.3.16`). The version number `3.2.20` is intentionally skipped: it exists as a
+  tagged-but-deliberately-unpublished version (see the 3.3.0-era changelog corrections).
+
+## [3.2.19] - 2026-07-16
+
+Farmers / `cans-upsert` reliability adoption + an ooze KPI counter fix. **Backwards-compatible.**
+Cut from the `v3.2.18` tag (not `master`, which carries the native GraphQL activity/dashboard
+readers depending on the unreleased gem `1.4.0`), so this ships needing only the published
+`ecoportal-api-graphql 1.3.14`.
+
+### Changed
+
+- **Floor `ecoportal-api-graphql` to `>= 1.3.14`** (was `>= 1.3.11`) — pulls the HttpClient
+  429/1015 resilience fix, so bulk `cans-upsert` / register-update live runs are no longer
+  aborted by a single Cloudflare edge rate-limit.
+
+### Fixed
+
+- **Ooze update KPI counters now count GraphQL updates.** `RegisterUpdateCase` tallied
+  `updated`/`failed` only when the result `is_a?(Ecoportal::API::Common::Response)`, but the
+  GraphQL compat layer returns an `Ecoportal::API::GraphQL::Compat::Response` — it duck-types
+  `success?`/`status` yet is not in that class hierarchy, so every GraphQL update was silently
+  uncounted (`Updated 0 (attempted: N)`, `Failed 0`) even when the write applied. The guard is
+  now a duck-type (`respond_to?(:success?)`); `false`/`nil` returns (dry-run / no-op) still skip.
+  **Note:** this fixes the *report* only — the updates themselves were already applying.
+
+## [3.2.18] - 2026-07-10
+
+Version-identity + regression-guard release. **No behaviour change** vs the fixed `3.2.17` build —
+this bump exists so the LocationDraft fix can be pinned/verified by version, and adds an offline
+guard so the dead-fragment class of bug can't reach production again.
+
+### Why this bump
+
+`3.2.17` shipped as **two different builds under one version**: the version was bumped to `3.2.17`
+on 2026-07-04 (`243822b9`), then the live-crash fix `352a9657` (LocationDraft dead-fragment
+convention) landed on 2026-07-05 — keeping the same `3.2.17` label. Because `3.2.17` is installed
+from git/path (unpublished), a consumer bundled in that ~26h window reports `3.2.17` yet lacks the
+fix. This crashed the **live act-gov** org-structure sync again on 2026-07-09 with the exact
+`uninitialized constant …Fragment::LocationDraft (NameError)`. Bumping to `3.2.18` makes the fixed
+build unambiguously identifiable: any consumer on `>= 3.2.18` provably has the fix.
+
+### Added
+
+- **Regression-guard spec for the dead-fragment convention.**
+  `spec/…/helpers/location/command/end_points/optimizations_spec.rb` scans every file under
+  `usecases/graphql/` and fails if any references a fragment via the removed `___Const__Fragment` /
+  `::Fragment::<Name>` constant convention (the exact NameError that crashed act-gov), and asserts
+  the three Location command payload procs still route fragments through the `spread :Name` registry
+  DSL. It is a SOURCE lint, not a full offline render: rendering needs the graphlient fork's
+  `to_query_string`/`spread` DSL, but eco-helpers' own bundle resolves stock graphlient `0.8.0` (the
+  fork is pinned only in the deployment/gem bundles). If eco-helpers later pins the fork in dev/test,
+  promote this to a real render guard like the gem's `tests/validate_queries.rb`.
+
+## [3.2.17] - 2026-07-04
+
+Native GraphQL template build+maintenance + ooze-native migration (strangler-fig): pure,
+non-breaking additions built ALONGSIDE the OozeRedirect shim. No `OozeSamples::*` name is
+flipped/redirected and the shim is untouched. **Not yet published** — the template Deploy loop binds
+to the gem's `Diff` module (gem v1.3.11), which is tagged but unpublished.
+
+### Fixed
+
+- **`-no-email` double-send guard typo.** `Location::Command::Service::TreeUpdate#email_digest` set
+  `{worfklow: {no_email: true}}` (misspelled key) after sending, so the "don't send the digest twice"
+  guard never took effect. Corrected to `workflow`. (Note: the primary `-no-email` check on the same
+  method already used the correct key, so a single `-no-email` run was already suppressed.)
+- **Location command optimizations — dead fragment convention (live crash).**
+  `Helpers::Location::Command::EndPoints::Optimizations` referenced fragments via the removed
+  `___Const__Fragment` constant convention (`___Ecoportal__API__GraphQL__Fragment__LocationDraft` /
+  `…__LocationsError`), which the gem's registry-based fragments no longer expose as Ruby constants →
+  `uninitialized constant … Fragment::LocationDraft (NameError)` when building a locations-draft
+  `addCommands`/`create`/`publish` request. Crashed the live act-gov tagtree / org-structure sync.
+  Now `spread :LocationDraft` / `spread :LocationsError`, matching the gem.
+
+### Dependencies
+
+- **Raised floors to the fixed stack: `ecoportal-api-graphql >= 1.3.11`, `ecoportal-api-v2 >= 3.3.3`.**
+  Stops the stale gem 1.3.9 (missing the LocationStructure `updatedAt`/`createdAt` selection fixes from
+  1.3.10) and the buggy v2 3.3.2 (Ruby-3.x `DoubleModel` cascade `TypeError`) from resolving on
+  consumers — both crashed the live act-gov integration.
+
+### Added
+
+- **`Helpers::Pages::OozeHandlers`** — native re-expression of `OozeSamples::Helpers::OozeHandlers`.
+  `merge_values(origin, append, type:, delimiter:)` dispatches on the GraphQL DataField TYPE STRING
+  (`PlainText`/`RichText` → newline; `Select`/`CrossReference`/`People`/`Checklist`/`ActionsList`/
+  `File`/`ImageGallery`/`Geo`/`Law` → delimiter join; `Date`/`Number`/`Gauge` → keep origin) instead
+  of `Ecoportal::API::V2::Page::Component::*` classes. `merge_arrays`/`array_indexes` ported verbatim.
+  Included into `Samples::Pages::Register::Base`, which also gains `#merge_field_values(field, append)`
+  (reads the field's own `#type` + current `#value`).
+- **`Samples::Pages::Register::TargetOozesUpdateCase`** — native counterpart of
+  `OozeSamples::TargetOozesUpdateCase`, subclassing the native `Register::Base`. Reads target page ids
+  from `options[:source][:file]` (first CSV column, header dropped), batches them, previews with
+  duplicate detection + proceed prompt, fetches each via `graphql.pages.get`, dedups by id, and hands
+  each page to `process_page`. `#each_page` (register-search) is disabled here to prevent an
+  accidental org scan.
+- **`Compat::Parity`** A/B parity harness — `RunResult` (canonical KPI + normalised per-page update
+  payload snapshot), `Comparison` (KPI/page-set/payload diffs + `equivalent?` verdict + report), and
+  `Harness` (orchestrates a legacy vs native run and compares; `.record` captures a run's observables).
+  Comparison logic is pure/offline-runnable; live capture of the two runs needs a test org + creds.
+- **`Helpers::Pages::TypedFieldsPairing`** — native re-expression of
+  `OozeSamples::HelpersMigration::TypedFieldsPairing`. Pairs data fields across two page models by
+  SAME type + SAME label, in two screenings (exact label, then mild: case-insensitive a-z with
+  bracketed content removed). Groups/dispatches by the GraphQL DataField TYPE STRING
+  (`PlainText`/`Select`/`Date`/... per `DataField::TYPE_MAP`) rather than v2 snake_case component
+  types; `EXCLUDED_TYPES` = `%w[TagField Chart FrequencyRateChart]` (never-pair). Tracks unpaired
+  src/dst fields + multi-candidate sources, with `resolve`/report helpers. Legacy class untouched.
+  This is the cross-template field-pairing (migration), DISTINCT from `OozeHandlers#merge_values`
+  (value-merge of one already-paired field).
+- **`Helpers::Pages::Copying`** — native counterpart of
+  `OozeSamples::HelpersMigration::Copying`. `copy_generic_paired_fields(src, dst)` runs
+  `TypedFieldsPairing` and copies each pair's content; `copy_field_content(src, dst)` dispatches on
+  the GraphQL DataField type string (`PlainText`/`Number`/`Date`/`Gauge` → `value=`, `RichText` →
+  `content=`, `Select` → `select_option`, `CrossReference` → `page_ids=`; other types left untouched).
+  The v2 regex/JSON hooked-field mapping layer (`copy_hooked_fields`) is NOT ported (later increment).
+- **`Samples::Pages::Register::MigrationCase`** — native counterpart of
+  `OozeSamples::RegisterMigrationCase`, subclassing the native `Register::Base` and mixing in
+  `Copying`. Iterates a source register, drafts a NEW entry of `TEMPLATE_ID` (via native `Creatable`),
+  pairs the source fields to the draft's fields and copies content across, runs the unpaired /
+  multi-pair reports, and hands the draft to `#custom_processing` for finalising. Per-page persistence
+  is the native create path (not the v2 batch queue). Native-only; no OozeSamples name flipped.
+
+Template automatic build & maintenance (Phase 5): native, offline-safe orchestration on top of the
+released gem's `Diff::Deploy` / `Diff::VersionDiff` / `Builder::Template`. Additive, no case flipped.
+
+- **`Samples::Pages::Template::Deploy`** — deploy → verify → monitor loop for template (workflow)
+  changes, driven by a gem `Diff::Deploy` command batch. Dry-run is the DEFAULT; live apply is gated
+  behind an explicit `commit: true` + executor. All components are session-less and offline-runnable
+  (the apply / re-read seams are injected).
+  - `Deploy::Applier` — wraps a gem `Diff::Deploy` plan. Dry-run records the batch it WOULD send;
+    `commit: true` applies it via any `execute_workflow_commands`-shaped executor (gem `Builder::Page`
+    facade adapted by `TargetBoundExecutor`). Refuses to apply while the plan has `unsupported`
+    changes unless `allow_partial: true` — nothing is guessed.
+  - `Deploy::RecordingExecutor` — offline stand-in that records batches and (with a `mutator`) replays
+    them onto an in-memory doc, so the pre/post drift check is runnable with no API call.
+  - `Deploy::DriftReport` — compares the APPLIED delta (a pre/post self-version `Diff::VersionDiff` of
+    the re-read target) to the INTENDED delta (the source diff the batch came from) on an id-free shape
+    signature; reports `missing` (under-applied) and `unexpected` (side-effect) changes honestly.
+  - `Deploy::Verifier` — pluggable post-deploy verification. `QaVerifier` wires the `ecoportal-qa`
+    check framework through a single seam when the gem is on the load path (NOT a hard dependency);
+    otherwise `NullVerifier` keeps the loop runnable and is honest that qa was unavailable.
+  - `Deploy::SyncReadiness` — given a register subset + its active template doc, reports which entries
+    CAN sync (all REQUIRED fields present, non-empty, and correctly typed) vs not, with per-entry
+    reasons.
+  - `Deploy::Loop` — orchestrates apply → drift → verify → sync-readiness and yields an aggregate
+    `Result` (`ok?` gate + human `report`). The applied-diff builder defaults to the gem's
+    `Diff::VersionDiff` (resolved lazily) and is injectable for offline use.
+- **`Samples::Pages::Template::CsvBuild`** — CSV → template BUILD pipeline reusing the existing
+  `Template::CommandEmitter` + the released gem `Builder::Template#create(commands:)`.
+  - `CsvBuild::FormatMap` — the SINGLE, isolated place the assumed columnar format lives (column names
+    + option delimiters), mapping a CSV row to a format-agnostic `RowSpec`. ⚠ The exact ~300-template
+    CSV column format is due ~mid-July 2026 and is NOT yet confirmed — only this file (and its spec)
+    changes when the real format lands.
+  - `CsvBuild::Parser` — groups rows into a stage → section → field tree preserving first-seen order.
+  - `CsvBuild::Builder` — replays the tree onto `CommandEmitter` (same placeholder-id threading), emits
+    the ordered `WorkflowCommand` batch (select options → `addSelectFieldOption`), and stamps a hidden
+    per-section anchor field for the identity convention (hidden-field + description). Offline/dry-run
+    by default (`#commands`, `#preview`); `#create!(template_facade)` is the live path (needs creds).
+  - `Template::CommandEmitter#field` gains optional `description:`/`required:` pass-throughs (additive).
+- **HONEST LIMITATIONS / deferred:**
+  - The released gem (1.3.9) does NOT yet ship `Diff::Deploy` / `Diff::VersionDiff` (unreleased on the
+    gem's main). The deploy loop is written against those APIs but touches them only via lazy/injected
+    seams, so it loads and its specs run offline today; a live drift check needs those classes released.
+  - The released gem's `addField` input drops any key outside
+    placeholderId/fieldType/label/stageId/sectionId/column, so the `description` identity token is NOT
+    yet persisted through addField — only the hidden anchor field's presence survives. Wiring is in
+    place so identity flows end-to-end once the gem's addField gains a description key.
+  - Live deploy/apply and live template creation both need credentials + a test org (the sandbox
+    cannot reach live). qa verification is stubbed behind `QaVerifier`'s single seam until qa is pinned.
+
+## [3.2.16] - 2026-07-02
+
+APIv2→GraphQL cutover — the OozeRedirect compat layer that runs the maintained ooze integrations
+(toocs-coding, cans-upsert, supplier-documents) on GraphQL. Requires ecoportal-api-graphql >= 1.3.9.
+
+### Fixed / Changed
+
+- **OozeRedirect slimmed onto the base OozeSamples loop** — removed the `with_each_entry` /
+  `update_ooze` / `process_ooze` overrides that duplicated and silently bypassed the base loop
+  (KPIs, dedup, queue, `dry_run_feedback`). Fetches go through `ooze → apiv2.pages.get` and saves
+  through `update_oozes → update_ooze → apiv2.pages.update`; a captured `submit!`/`sign_off!` rides
+  along on the single `updatePage` via `Input::Page::Update.from_model` (reads the `_compat_*` flags).
+- **`dirty?`** also treats a pending `submit!`/`sign_off!` as dirty (so a submit-only page still saves).
+- **`OozeBaseCase#dry_run_feedback`** prints an affirmative `[dry-run] would create/update <ref>` line.
+- **`RegisterUpdateCase#enqueue`** accepts any duck-typed entry (`#dirty?` + `#as_update`), not just
+  v2 `Page`/`PageStage` — GraphQL compat pages queue correctly under OozeRedirect.
+
 ## [3.2.15] - 2026-05-xx
 
 ### Added

data/lib/eco/api/usecases/CLAUDE.md

@@ -0,0 +1,78 @@
+# usecases
+
+The use-case registry and all built-in case base classes for scripting against EcoPortal.
+
+---
+
+## What a use case is
+
+A use case is a self-contained, named, runnable unit of work. It registers itself with
+the CLI framework, receives `session`, `options`, and `usecase` from the runner, and
+executes its `process` (or `process_ooze` / `process_page`) method.
+
+```
+CLI invokes rake → rake finds registered case → UseCase#launch → main() → process()
+```
+
+---
+
+## Directory structure
+
+| Path | What lives there |
+|------|-----------------|
+| `graphql/` | GraphQL-native base cases + samples (see `graphql/CLAUDE.md`) |
+| `ooze_samples/` | APIv2/REST base cases: `OozeBaseCase`, `RegisterUpdateCase` |
+| `ooze_cases/` | Concrete built-in ooze cases (export register, etc.) |
+| `default/` | Built-in people, location, and utility cases |
+| `default_cases/` | Loader and samples for default cases |
+| `samples/` | Misc driver samples |
+| `graphql.rb` | GraphQL use case loader |
+| `ooze_samples.rb` | Ooze/REST use case loader |
+| `default.rb` | Default use case loader |
+
+---
+
+## Adding a new use case
+
+1. Subclass the appropriate base:
+
+   | Your use case | Inherit from |
+   |---|---|
+   | Process pages in a register (update workflow) | `Eco::API::UseCases::GraphQL::PageCase` |
+   | Process pages org-wide (cross-register, audit) | `Eco::API::UseCases::GraphQL::OrgPageCase` |
+   | Custom GraphQL script (export, report, one-off) | `Eco::API::UseCases::GraphQL::Base` |
+   | Legacy APIv2 register update | `Eco::API::UseCases::OozeSamples::RegisterUpdateCase` |
+
+2. Set `name` and `type`:
+   ```ruby
+   name 'my-case-name'   # CLI identifier: called with -my-case-name
+   type :other           # :people | :contractors | :other
+   ```
+
+3. Override the entry point (`process_page`, `process`, or `process_ooze`).
+
+4. Register in the org's `config/cli.rb`:
+   ```ruby
+   cases.add('-my-case-name', :other, 'Description')
+   ```
+
+---
+
+## How cases are launched
+
+`Eco::API::UseCases::UseCase#launch` calls `callback.call(*uio.params)` where the
+callback is bound to `method(:main)`. Before launch, `@session` and `@options` are
+injected into the instance — subclasses access them via the `attr_reader` in `CaseEnv`.
+
+The `:other` type passes `(session, options, usecase)` positionally to `main`.
+For `GraphQL::Base` subclasses the signature is `main(*_args)` — `session` and
+`options` are already available via the helpers module before `main` is called.
+
+---
+
+## Related
+
+- `graphql/CLAUDE.md` — GraphQL case hierarchy, PageCase/OrgPageCase
+- `ooze_samples/` — legacy v2 cases (RegisterUpdateCase, OozeBaseCase)
+- `eco-helpers/CLAUDE.md` — top-level gem context
+- `ecoportal-api-graphql` — upstream gem providing `SearchConf`, `Compat::Pages`, etc.

data/lib/eco/api/usecases/default/pages.rb

@@ -0,0 +1,30 @@
+module Eco
+  module API
+    class UseCases
+      class Default
+        # Namespace for CLI-integrated page use cases.
+        # These are concrete, fully functional cases exposed to all org environments.
+        #
+        # == Convention
+        # Cases here should:
+        # - Inherit from Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
+        #   (or OrgPage::Base for org-wide operations)
+        # - Be registered in the org's config/cli.rb
+        # - Be as org-agnostic as possible (accept register_id, filters via options)
+        #
+        # == Adding a new default page case
+        # 1. Create the file here: default/pages/my_case.rb
+        # 2. Inherit from the appropriate pages sample base class
+        # 3. Require it below
+        # 4. Wire CLI registration in usecases/default_cases/samples.rb or the
+        #    org's config/cli.rb
+        #
+        # == Currently
+        # No default page cases yet — add them here as common patterns emerge
+        # across org implementations.
+        module Pages
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/CLAUDE.md

@@ -0,0 +1,120 @@
+# usecases/graphql
+
+GraphQL-native use case base classes and helpers. All cases here work directly with
+`ecoportal-api-graphql` — no v2 REST layer, no ooze objects.
+
+---
+
+## Class hierarchy
+
+```
+Eco::API::Common::Loaders::UseCase                           (registration + launch)
+    ↓
+Eco::API::UseCases::GraphQL::Base                            ← universal GraphQL env
+    ├── GraphQL::Samples::Pages::Page::Base                  ← register-scoped pages
+    │       ├── GraphQL::Samples::Pages::OrgPage::Base       ← org-wide pages
+    │       └── your subclass (process_page, search_conf)
+    └── your subclass directly (custom scripts: exports, reports, one-offs)
+```
+
+Samples live under `samples/pages/` — NOT in the `graphql/` root. The root only
+has `base.rb`, `helpers.rb`, `utils.rb`, and `samples.rb`.
+
+---
+
+## Base — `graphql/base.rb`
+
+Universal GraphQL environment. Provides `graphql`, `session`, `options`, `config`,
+`simulate?`, `log`, `backup` via `Helpers::Base` (see `helpers/CLAUDE.md`).
+
+Override `process` to write your script:
+```ruby
+class MyCase < Eco::API::UseCases::GraphQL::Base
+  name 'my-case'
+  def process
+    graphql.currentOrganization.contractorEntities.each { |c| puts c.name }
+  end
+end
+```
+
+---
+
+## Pages — `samples/pages/`
+
+Page processing base cases. Follow the hierarchy: `page/base` → `org_page/base`.
+
+### `samples/pages/page/base.rb` — `Samples::Pages::Page::Base`
+
+For **register-scoped** page update workflows.
+
+**Class methods:** `register_id 'REG_ID'`, `batch_size 50` (default)
+
+**Override points:**
+- `process_page(page)` — **required** — transformation for one page
+- `search_conf` — optional — call `super` to keep register scope, then add filters
+
+**Protected helpers:** `update_page`, `skip(reason)`, `each_page`
+
+**KPI readers:** `total_pages`, `processed_pages`, `updated_pages`, `skipped_pages`, `failed_pages`
+
+**DSL (via `samples/pages/page/dsl.rb`):** `sc`, `in_register`, `state_is`, `external_id_eq`, `updated_since`
+
+```ruby
+class Custom::UseCase::UpdateStatus < Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
+  name 'update-status'
+  register_id 'REG_ABC'
+
+  def search_conf
+    super.filter(state_is(:active))
+  end
+
+  def process_page(page)
+    page.name = page.name.upcase
+    update_page(page)
+  end
+end
+```
+
+### `samples/pages/org_page/base.rb` — `Samples::Pages::OrgPage::Base`
+
+Inherits `Page::Base`. `search_conf` starts empty (org-wide, no register scope).
+Use for: archive sweeps, cross-register audits, bulk org operations.
+
+---
+
+## Samples — `graphql/samples/`
+
+Built-in ready-to-use case implementations:
+- `samples/location.rb` — location structure management cases
+- `samples/contractors.rb` — contractor entity cases
+
+See `samples/CLAUDE.md` for details.
+
+---
+
+## Helpers — `graphql/helpers/`
+
+Mixins providing domain-specific access patterns. See `helpers/CLAUDE.md`.
+
+---
+
+## Loader order in `graphql.rb`
+
+```ruby
+require 'graphql/helpers'   # environment mixins (graphql, session, simulate? etc.)
+require 'graphql/utils'     # utility modules (SFTP etc.)
+require 'graphql/base'      # GraphQL::Base — universal foundation
+require 'graphql/samples'   # sample cases: location, contractors, pages, ...
+  # └─ graphql/samples/pages.rb
+  #      └─ pages/page.rb        → page/dsl.rb, page/base.rb
+  #      └─ pages/org_page.rb    → org_page/dsl.rb, org_page/base.rb
+```
+
+Page base cases are in `samples/pages/` — NOT in the `graphql/` root.
+Custom org cases are NOT loaded here — they live in the implementation repo.
+
+## default/pages/
+
+CLI-integrated page use cases go in `default/pages/` (mirroring `default/locations/`
+and `default/people/`). Currently empty — add cases there when a pattern is common
+enough to expose to all org environments. See `default/pages.rb` for the convention.

data/lib/eco/api/usecases/graphql/compat/ooze_redirect/dirty_array.rb

@@ -0,0 +1,22 @@
+module Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  # Array subclass that calls the field's setter when elements are appended,
+  # ensuring GraphQL dirty-tracking fires on `fld.people_ids << value`.
+  class DirtyArray < Array
+    def initialize(field, data)
+      @field = field
+      super(Array(data))
+    end
+
+    def <<(value)
+      super
+      @field.people_ids = to_a
+      self
+    end
+
+    def push(*values)
+      super
+      @field.people_ids = to_a
+      self
+    end
+  end
+end