eco-helpers 3.3.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 573a9ed21173c949849363f9e92875fc79981e410144a6c3fe101fdfcd4b9062
-  data.tar.gz: c12a639bb7775e0d43459c5bfe534fae12552c760d608b2192c052b12c1828a0
+  metadata.gz: 0d846f9dd8c67e9ece8e82f76b48f57abb6f2281a827906fa0deea759793a2a4
+  data.tar.gz: 31010d6385deea25c65e005f2d056e07cc1c00e18cc3257c080863a9042c5393
 SHA512:
-  metadata.gz: a3fb82eb08b5421db3bcca403257eb694aaf4844ed11c82c2e2a66211b9a13d14ae4b7941c42a720b74e5b5e09df39f8846223ed777cf21095d42d0086a73f89
-  data.tar.gz: c51eb9e14c75aedb26e68562d15801de0bbaf376983254d809ed0024968c1a4117de12e2f6444647ad75ce51f50847d684d5261d3b10e6897bd8454f6e7ef9af
+  metadata.gz: ca7ad30915e09c003d99c0cf291b0ef2a1834179883de98402380d144bb231cf9f12f2fe802b5b2fed2387b8d63e6e3eee8e4363decdd3636863af0bc702edc8
+  data.tar.gz: ed532533a05a25f09b65118104a8627f7bf0fde3b212b2fcd562d499770fdd19de4588caefd388eebb5c91cd9689ab6cbfcf3456e47dafeb69acfab9231956a8

data/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [3.4.0] - 2026-09-29
+
+**MERGE ONLY AFTER `ecoportal-api-graphql` 3.0.0 IS PUBLISHED** -- this release's gemspec
+floor (`~> 3.0`) cannot resolve against rubygems.org until then; tested here against a
+locally built 3.0.0 CANDIDATE gem (see `docs/worklog.md`'s 2026-09-29 entry for the exact
+build/install steps), not the published artifact.
+
+### Changed
+
+- **BREAKING for consumers still on `ecoportal-api-graphql` 2.x:** requires
+  `ecoportal-api-graphql ~> 3.0` (was `~> 2.0`). That gem's own 3.0.0 removes
+  `Base::Page::DataField::ImageGallery#file_container_ids` / `#file_container_ids=` --
+  an Image Gallery image was never a `FileContainer`. Replaced by `#images` / `#image_ids` /
+  `#add_source_images([{source_id:, file_name:}, ...])` after
+  `FileUpload::Client#upload_image`. A repo-wide sweep of `eco-helpers` itself for
+  `file_container_ids` / `fileContainerIds` / `fileContainers` found **0 hits** -- no caller
+  in `lib/`, `spec/`, `docs/`, `bin/` used the removed accessors (the one look-alike,
+  `FileField#file_container_id` in `lib/eco/api/usecases/ooze_samples/helpers_migration/
+  copying.rb`, is the UNRELATED APIv2/REST `File` field type's own singular accessor, not
+  Image Gallery, not affected). No code change was needed in `eco-helpers` for this bump.
+- `Eco::API::Session::Concurrency::BoundedWorkerPool` / `RetryPolicy`
+  (`lib/eco/api/session/concurrency/`) are now the CANONICAL, supported concurrency
+  primitives in this gem (dropped the "draft, nothing has switched to this copy yet"
+  header wording) -- see `README.md`'s new "Concurrency primitives" section. No
+  pre-existing inline `Thread.new`/`Queue.new`/subprocess-retry-loop exists anywhere under
+  `lib/eco/api/session` or `lib/eco/api/usecases` to migrate onto them (checked by grep at
+  promotion time); a future caller picks these up directly, as-is.
+
+### Fixed
+
+- `Eco::Language::Klass::AutoLoader#autoload_children!` only tolerated a `TypeError` from a
+  malformed pending child (its own comment: "must be the singleton class"); a pending child
+  raising any OTHER `StandardError` while being constructed (e.g. an anonymous, never fully
+  configured `Class.new(SomeAutoloadedBase)` test double left alive in `ObjectSpace` by an
+  entirely unrelated spec elsewhere in the same process -- `Parser`/`ErrorHandler`
+  characterization specs create these on purpose) propagated out of the NEXT, unrelated
+  caller's own `autoload_children!` cycle instead. Broadened the rescue to `TypeError,
+  StandardError`, matching the existing rescue's own documented intent ("can't create from
+  this class... just ignore"). Pre-existing, GC-timing-sensitive flake -- confirmed
+  reproducible (non-deterministically) against the CURRENT `ecoportal-api-graphql` 2.2.0
+  floor too, not something the 3.0 bump introduced; surfaced while testing this release
+  against the 3.0.0 candidate, where it reproduced deterministically across three
+  consecutive runs before the fix and cleared across three consecutive runs after.
+
+## [3.3.2] - 2026-09-02
+
+### Fixed
+
+- Gemspec `spec.files` allowlisted by ROOT DIRECTORY (`lib/`, `exe/`) rather than by full path,
+  so any non-`.rb` file added under `lib/` shipped silently. As of 3.3.1 that was five `CLAUDE.md`
+  agent-instruction files under `lib/eco/api/usecases/`. `spec.files` is now a full-path
+  allowlist — `lib/**/*.rb`, three named JSON files genuinely read at runtime
+  (`preferences_reference.json`, `presets_integrity.json`, `presets_values.json`), and
+  `README.md` / `CHANGELOG.md` / `LICENSE` at the root — intersected with `git ls-files`.
+  `spec/packaging_spec.rb` pins the allowlist so this cannot regress silently again.
+
 ## [3.3.1] - 2026-08-13
 
 ### Fixed
@@ -11,7 +69,7 @@ All notable changes to this project will be documented in this file.
   actual bytes. Both read branches (BOM and plain) now use binary mode (`mode: 'rb'`), preserving
   the bytes exactly; BOM stripping is unchanged. Linux behaviour is identical before and after
   (text mode never translated anything there) — this makes Windows match Linux. Surfaced by Travis
-  on the mns EPT-1607 tooltip CSV (multi-org-idle `BLOCKED-TR-04`).
+  on a customer's tooltip CSV (reported from a downstream script repo).
 
   **Precision note (2026-08-13, verified against the motivating file before this version was
   tagged):** the earlier draft of this entry claimed `Eco::CSV.read` raised
@@ -51,7 +109,7 @@ depends on whether the consumer also declares graphql directly:
 - A consumer declaring **only** `eco-helpers '~> 3.2'` adopts 3.3.0 on its next `bundle update`,
   and reaches **graphql 2.0.0 transitively**.
 - A consumer declaring **both** `eco-helpers '~> 3.2'` and `ecoportal-api-graphql '~> 1.3'` (which
-  is the case for `multi_org_api` and `multi-org-idle`) does **not** silently adopt — it **fails to
+  is the case for two internal script repos) does **not** silently adopt — it **fails to
   resolve**, because 3.3.0 requires graphql `~> 2.0`.
 
 So the "2.0.0 gates adoption for free" argument only ever covered **direct** graphql dependencies.
@@ -60,7 +118,7 @@ Both consumers were pinned deliberately on 2026-08-13 rather than left to discov
 ★ **`3.2.20` was tagged but deliberately NEVER PUBLISHED.** rubygems goes 3.2.19 → 3.3.0. The tag
 marks real history (the point where the 3.2.19 hotfix line rejoined master) but the gem was not
 pushed, and **must not be**: it predates the `spec.files` allowlist fix below and would ship
-internal `.ai-assistance/` and `docs/` content to rubygems. Its content is not lost — 3.3.0
+internal AI-tooling and `docs/` content to rubygems. Its content is not lost — 3.3.0
 descends from it. Anything needing the `Eco::API::Custom::Cli` reunification must use **3.3.0**,
 not a `~> 3.2.0` pin.
 
@@ -75,7 +133,7 @@ check.
 recorded, treat any `OozeRedirect` run against customer data as unproven — dry-run first.
 
 ★ **The published gem is now `lib/` only.** `spec.files` excluded just `test|spec|features`, so
-every top-level directory added since shipped by default — `.ai-assistance/` internal notes,
+every top-level directory added since shipped by default — internal AI-tooling notes,
 `docs/` (including the rolling worklog) and `.claude/`. `spec.files` is now an allowlist
 (`lib/`, `exe/`, README, LICENSE, CHANGELOG). All `lib/` files are unchanged; nothing outside
 `lib/` was ever loaded at runtime. Same fix as `ecoportal-api-graphql` 2.0.0.
@@ -84,7 +142,7 @@ every top-level directory added since shipped by default — `.ai-assistance/` i
 
 Reunites the released `3.2.19` hotfix line with `master`. `3.2.19` was cut from the `v3.2.18` tag
 and **never merged back**, so two halves were split across branches: `master` carried
-`Eco::API::Custom::Cli` (unreleased since 2026-07-25, and the reason `mns/config/cli.rb` could not
+`Eco::API::Custom::Cli` (unreleased since 2026-07-25, and the reason a downstream CLI could not
 load on any published gem) while `3.2.19` carried the ooze KPI counter fix and the graphql floor.
 This release carries both. Dependency floors are the max of each side.
 
@@ -145,7 +203,7 @@ replaces on release.
 
 ## [3.2.19] - 2026-07-16
 
-Farmers / `cans-upsert` reliability adoption + an ooze KPI counter fix. **Backwards-compatible.**
+A customer's `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`.
@@ -178,7 +236,7 @@ guard so the dead-fragment class of bug can't reach production again.
 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
+fix. This crashed the **live customer** 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.
 
@@ -187,7 +245,7 @@ build unambiguously identifiable: any consumer on `>= 3.2.18` provably has the f
 - **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
+  `::Fragment::<Name>` constant convention (the exact NameError that crashed a customer sync), 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
@@ -212,7 +270,7 @@ to the gem's `Diff` module (gem v1.3.11), which is tagged but unpublished.
   `___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.
+  `addCommands`/`create`/`publish` request. Crashed a customer's live tagtree / org-structure sync.
   Now `spread :LocationDraft` / `spread :LocationsError`, matching the gem.
 
 ### Dependencies
@@ -220,7 +278,7 @@ to the gem's `Diff` module (gem v1.3.11), which is tagged but unpublished.
 - **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.
+  consumers — both crashed a customer's live integration.
 
 ### Added
 

data/README.md

@@ -1,6 +1,34 @@
 # API Helpers (eco-helpers)
 
-Some helpers to define a framework of use cases.
+## Why this repo exists
+
+`eco-helpers` is the team's **central integrations library** -- one of the oldest repos in the
+fleet. It sits between the raw EcoPortal API clients (`ecoportal-api`, `ecoportal-api-v2`,
+`ecoportal-api-graphql`) and the end scripts, adding file management/access, SFTP access, and
+more (`net-sftp`, `net-ssh`, `aws-sdk-s3` are runtime dependencies -- see `eco-helpers.gemspec`).
+
+> "If there is a repo that should somehow be the reference of our integrations that is the
+> eco-helpers repo... [ep-graphql is powerful but raw] ...but if we have an intermediate layer
+> with helpers that allow to build integrations by taking into account not just raw api access,
+> but also file managing/access, SFTP access, etc. that is the eco-helpers for sure."
+> -- owner, 2026-09-23
+
+```mermaid
+flowchart LR
+  A["Raw API clients<br/>ecoportal-api / -v2 / -graphql"] --> B["eco-helpers<br/>integrations layer"]
+  B --> C["End scripts<br/>automation, CLI, use cases"]
+```
+*Layering per the owner's own description (source: memory
+`project-imports-process-and-eco-helpers-owner-truth.md`, 2026-09-24).*
+
+### What is inside
+
+- `lib/eco/api/` -- API integration layer (session, use-cases, microcases, policies, org resources)
+- `lib/eco/cli/` + `lib/eco/cli_default/` -- CLI framework and default options/filters/people workflows
+- `lib/eco/csv/` -- CSV reading, streaming, splitting
+- `lib/eco/data/` -- data utilities (fuzzy match, hashes, locations, strings, files)
+- `lib/eco/language/` -- logging, curry, and auxiliary utilities
+- `lib/eco/assets/` -- static assets (language files etc.)
 
 ## Installation
 
@@ -19,6 +47,39 @@ Or install it yourself as:
     $ gem install eco-helpers
 
 
+## Concurrency primitives
+
+`Eco::API::Session::Concurrency` (`lib/eco/api/session/concurrency/`) is the supported home
+for session-level concurrency primitives, as of 3.4.0:
+
+- **`BoundedWorkerPool`** -- a generic, bounded pool of OS threads (pure `Thread`/`Queue`/
+  `Mutex`, no extra gem) for running the SAME block over a list of items with a hard ceiling
+  on how many run simultaneously. Results come back in the same order as the input,
+  regardless of finish order; one item's block raising is captured as that item's own
+  `Result#error`, never re-raised, never aborts sibling work already in flight or queued
+  (unless `stop_on_error: true`). See the class's own header for the full contract and
+  thread-safety notes.
+- **`RetryPolicy`** -- a pure decision service (never sleeps itself) for whether/how long to
+  wait before retrying a whole failed subprocess call, given its captured output and exit
+  status: rate-limit/5xx-aware, bounded exponential backoff with full jitter, honours a
+  captured `Retry-After` header. See the module's own header for why an OUTER,
+  subprocess-level retry is worth having even though the underlying GraphQL gem already
+  retries transient errors INSIDE one call.
+
+Both are generic (no case-specific or org-specific logic) and fully specced against
+synthetic blocks only -- no subprocess, no network, nothing case-specific. See
+`spec/eco/api/session/concurrency/`.
+
 ## Changelog
 
 See {file:CHANGELOG.md} for a list of changes.
+
+<!-- audit-status:start -->
+### Fleet audit status
+
+This repo is under the Fleet Audit & Amendment Programme (FAAP). No audit run yet -- this is the notice MR; the first `granular`-tier run populates this block with counts by severity and status.
+
+Guidelines (read before any change): `docs/audits/guidelines.md`
+Deviations register: `docs/audits/deviations.md`
+Run index: `docs/audits/README.md`
+<!-- audit-status:end -->

data/lib/eco/api/session/concurrency/bounded_worker_pool.rb

@@ -0,0 +1,150 @@
+# PROMOTED FROM a downstream script repo (services/bounded_worker_pool.rb @ 41dedad)
+# NAMESPACE: PROVISIONAL (owner ruling DSL-02) -- kept the original class/module name
+# (`BoundedWorkerPool`) under `Eco::API::Session::Concurrency::*`, the session-level
+# concurrency primitives location proposed by WP-6 (see
+# the repo's internal docs, Option A).
+#
+# CANONICAL, 3.4.0 (release/3.4.0-prep) -- this is the supported concurrency primitive for
+# a bounded pool of OS threads in this gem; see `README.md`'s own "Concurrency primitives"
+# section. No PRE-EXISTING inline `Thread.new`/`Queue.new` concurrency exists anywhere else
+# under `lib/eco/api/session` or `lib/eco/api/usecases` to migrate onto this (checked by
+# grep, both directories, at promotion time) -- there was nothing to switch, so none of this
+# gem's own call sites change as part of this promotion; a FUTURE caller (this gem's own
+# batch/CLI code, or a downstream consumer such as a downstream script's wave runner, the
+# original motivating caller) picks this up directly, as-is.
+#
+# the wave-concurrency work (2026-09-19) -- generic, reusable bounded-concurrency runner. Pure
+# Ruby stdlib (`Thread`/`Queue`/`Mutex`) -- no new gem, matching this repo's own "PLAIN DATA IN/
+# service-first" convention (see any other `Custom::Template::Services::*` file's header).
+#
+# WHY THIS EXISTS: `run_wave.rb` shells out to `ruby main.rb ...` once PER ITEM, per stage
+# (build/force-install/publish/tooltips) -- ~47 items, each a live network round trip, run
+# strictly sequentially. A pass is minutes of network WAIT, not CPU work, so a bounded pool of
+# OS threads (each blocking on its own `Open3.capture3` call) is the right tool: Ruby (MRI)
+# threads release the GVL during blocking I/O (`Open3.capture3` waits on the child process, a
+# blocking syscall), so N threads genuinely overlap N in-flight subprocess calls rather than
+# contending for CPU.
+#
+# CONTRACT (every point specced in isolation, synthetic blocks only -- no subprocess, no
+# network, nothing case-specific here):
+#   - `concurrency:` is a HARD CEILING on simultaneously-RUNNING blocks -- never exceeded.
+#   - Results come back in the SAME order as `items`, regardless of which one finishes first
+#     (a slow item 1 and a fast item 2 must never swap positions in the returned Array).
+#   - One item's block RAISING is CAPTURED as that item's own `Result#error`, never re-raised
+#     to the caller, and never aborts sibling work already in flight or already queued --
+#     UNLESS `stop_on_error:` says otherwise (below).
+#   - Empty `items` returns `[]` immediately, no thread ever spawned.
+#
+# `stop_on_error:` (default `false`, OPT-IN, generic -- not `run_wave.rb`-specific): once ANY
+# dispatched item's block raises, no item still WAITING in the queue is ever started (each
+# such item's own `Result#skipped?` reads `true`, `#value`/`#error` both `nil`) -- but anything
+# ALREADY running when the failure is observed is allowed to finish (there is no clean way to
+# interrupt a live `Open3.capture3` mid-flight, and killing the child process would leave that
+# item's own live state ambiguous, worse than letting it complete). At `concurrency: 1` this
+# reproduces "stop at the first failure, never attempt the next item" EXACTLY -- with a single
+# worker, "already running" and "already failed" can never overlap, so the second item is
+# always still in the QUEUE (never started) the instant the first one fails. `run_wave.rb`'s
+# own force-install/build wiring relies on this exact property for byte-for-byte parity with
+# its pre-concurrency sequential behaviour at `--concurrency 1` (see
+# `run_wave_concurrency_spec.rb`'s own "concurrency 1 equivalence" examples).
+#
+# THREAD SAFETY OF `results[index] = ...` FROM MULTIPLE THREADS: safe under MRI (this repo's
+# only Ruby implementation, per rbenv) -- the GVL serializes bytecode execution, so concurrent
+# writes to DISTINCT indices of one Array never race or corrupt its internal structure (a
+# well-established MRI pattern; JRuby/TruffleRuby would need an explicit lock here too, but
+# this repo does not target them). The ONE piece of state actually SHARED and mutated across
+# threads (`aborted`, for `stop_on_error:`) is behind an explicit `Mutex` regardless, so this
+# file makes no silent assumptions beyond that documented one.
+
+module Eco
+  module API
+    class Session
+      module Concurrency
+        module BoundedWorkerPool
+          # One item's own outcome. Exactly one of `value`/`error` is non-nil unless `skipped?`
+          # is true, in which case both are `nil` -- the block was never even called for it.
+          Result = Struct.new(:item, :value, :error, :skipped, keyword_init: true) do
+            def skipped?
+              !!skipped
+            end
+
+            # @return [Boolean] true only for a NORMAL completion -- neither raised nor skipped.
+            def ok?
+              !skipped? && error.nil?
+            end
+          end
+
+          class << self
+            # @param items [Array] anything, plain data -- never mutated.
+            # @param concurrency [Integer] hard ceiling on simultaneously-RUNNING blocks. Values
+            #   `<= 0` are treated as `1` (never zero threads, never negative) -- callers own
+            #   their own upper-bound policy (`run_wave.rb`'s own `--concurrency` option caps at
+            #   8, enforced there, not here: this file is generic and takes no opinion on what a
+            #   sane ceiling is for any particular caller).
+            # @param stop_on_error [Boolean] see the file header.
+            # @yieldparam item [Object] one element of `items`.
+            # @yieldreturn [Object] becomes that item's `Result#value`.
+            # @return [Array<Result>] one per `items` element, in `items`' own order.
+            def run(items, concurrency:, stop_on_error: false, &block)
+              list = Array(items)
+              return [] if list.empty?
+
+              worker_count = [concurrency.to_i, 1].max
+              run_state = RunState.new(
+                queue: build_queue(list, worker_count), results: Array.new(list.size),
+                abort_state: {aborted: false}, state_mutex: Mutex.new, stop_on_error: stop_on_error, block: block
+              )
+
+              threads = Array.new(worker_count) { Thread.new { worker_loop(run_state) } }
+              threads.each(&:join)
+
+              run_state.results
+            end
+
+            # Bundles the per-run shared state every worker thread reads/writes, so
+            # `#worker_loop`/`#run_one` stay under the 5-parameter style ceiling without losing
+            # any of it -- plain data, no behaviour of its own. Internal (declared above `private`
+            # only because Ruby constants ignore access modifiers -- rubocop Lint/UselessConstantScoping).
+            RunState = Struct.new(:queue, :results, :abort_state, :state_mutex, :stop_on_error, :block,
+                                  keyword_init: true)
+
+            private
+
+            # One `[index, item]` pair per real item, `worker_count` `:done` sentinels at the
+            # tail (one per worker, so every worker eventually sees its own stop signal and the
+            # pool's own `Thread#join`s all return -- a `Queue` blocks `#pop` forever otherwise).
+            def build_queue(list, worker_count)
+              queue = Queue.new
+              list.each_with_index {|item, index| queue << [index, item]}
+              worker_count.times { queue << :done }
+              queue
+            end
+
+            def worker_loop(run_state)
+              loop do
+                entry = run_state.queue.pop
+                break if entry == :done
+
+                index, item = entry
+                if run_state.stop_on_error && run_state.state_mutex.synchronize {run_state.abort_state[:aborted]}
+                  run_state.results[index] = Result.new(item: item, value: nil, error: nil, skipped: true)
+                  next
+                end
+
+                run_one(index, item, run_state)
+              end
+            end
+
+            def run_one(index, item, run_state)
+              value = run_state.block.call(item)
+              run_state.results[index] = Result.new(item: item, value: value, error: nil, skipped: false)
+            rescue StandardError => e
+              run_state.results[index] = Result.new(item: item, value: nil, error: e, skipped: false)
+              run_state.state_mutex.synchronize {run_state.abort_state[:aborted] = true} if run_state.stop_on_error
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/session/concurrency/retry_policy.rb

@@ -0,0 +1,139 @@
+# PROMOTED FROM a downstream script repo (services/retry_policy.rb @ 41dedad)
+# NAMESPACE: PROVISIONAL (owner ruling DSL-02) -- kept the original class/module name
+# (`RetryPolicy`) under `Eco::API::Session::Concurrency::*`, the session-level concurrency
+# primitives location proposed by WP-6 (see
+# the repo's internal docs, Option A).
+#
+# CANONICAL, 3.4.0 (release/3.4.0-prep) -- this is the supported subprocess-level retry
+# decision primitive in this gem; see `README.md`'s own "Concurrency primitives" section.
+# `lib/eco/api/session/batch/launcher/retry.rb`'s own `offer_retry_on`/`batch_mode_on` are a
+# DIFFERENT, PRE-EXISTING retry mechanism (interactive Y/n prompt + a fixed
+# `ALLOWED_RETRIES` count around the people-batch HTTP endpoint's own error classes,
+# `Ecoportal::API::Errors::TimeOut`/`StartTimeOut`) -- not a shelled-out-subprocess retry,
+# nothing to switch onto this file. `lib/eco/api/usecases/graphql/samples/location/service/
+# tree_diff.rb`'s `sleep(5)` is an unconditional cooldown pause between comparisons, not a
+# retry loop either. Neither is this file's concern; checked (grep, both directories) at
+# promotion time -- there is no PRE-EXISTING inline concurrency/retry loop that duplicates
+# this file's own job to wire onto it. A FUTURE caller (this gem's own batch/CLI code, or a
+# downstream consumer such as a downstream script's wave runner, the original motivating
+# caller) picks this up directly, as-is.
+#
+# the wave-concurrency work (2026-09-19) -- decides WHETHER/HOW LONG to wait before retrying
+# one shelled-out subprocess call, never sleeps itself (pure decision service, easily specced
+# without a slow test) and never distinguishes idempotent-vs-not (that policy is the CALLER's
+# own job -- `run_wave.rb` only ever calls this for stages it has independently classified as
+# safe to retry -- see that file's own PER-STAGE RETRY TABLE comment).
+#
+# WHY A SUBPROCESS-LEVEL RETRY EXISTS AT ALL, GIVEN THE GEM ALREADY RETRIES: confirmed by
+# reading `ecoportal-api-graphql` (2.2.0) `lib/ecoportal/api/common/graphql/http_client.rb`
+# (`#execute`'s own comment, verbatim): every GraphQL call already routes through the
+# inherited `Common::Client` pipeline ("instrument -> with_retry { rate_throttling }"), which
+# already retries 429/Cloudflare-1015/5xx/connection errors INSIDE one call, transparently, long
+# before either the case code or this file ever sees anything. So by the time a shelled-out
+# `ruby main.rb ...` subprocess actually EXITS non-zero for an HTTP reason, that gem-level
+# budget has ALREADY been exhausted (or the whole process crashed before ever making a call,
+# e.g. a DNS blip at startup). Retrying the WHOLE subprocess is therefore a coarser, OUTER
+# layer of defence -- a fresh process gets a FRESH inner retry budget too (useful for
+# transient token/DNS issues an in-process retry cannot fix) -- not a duplicate of the gem's
+# own retries.
+#
+# THE MARKER THIS FILE READS -- NO CASE-FILE CHANGE NEEDED: grepped every
+# downstream template case file for an HTTP-status-distinguishing marker
+# (429/Retry-After/5xx) -- none add one themselves; they let the gem's own exception surface
+# verbatim on an uncaught crash. That exception already IS a stable, distinguishing marker:
+# `Ecoportal::API::Common::Client::Error::UnexpectedServerError#initialize` (ecoportal-api
+# 0.10.18, lib/ecoportal/api/common/client/error.rb) formats its message
+# `"Code: #{code} -- Error: #{msg}"` -- printed verbatim to STDERR (captured into `execute`'s
+# own combined stdout+stderr) whenever a subprocess crashes uncaught on a non-2xx HTTP
+# response. `HTTP_CODE_PATTERN` below matches THAT exact, already-existing text -- nothing was
+# added to any case file for this to work. Recorded here as an INFERRED-FROM-STATIC-READ
+# finding, not live-verified against a real 429 -- if a live retry never actually fires when
+# expected, re-check this pattern against a real crash's captured output first.
+module Eco
+  module API
+    class Session
+      module Concurrency
+        module RetryPolicy
+          # HTTP statuses worth retrying the WHOLE subprocess for: rate limiting (429) and the
+          # standard 5xx server-error family. Never 4xx other than 429 (a 400/403/404/422 is a
+          # REQUEST defect -- retrying it verbatim would just fail the same way every time).
+          RETRYABLE_HTTP_CODES = [429, 500, 502, 503, 504].freeze
+
+          # See the file header -- `Ecoportal::API::Common::Client::Error::UnexpectedServerError`'s
+          # own message format, verbatim.
+          HTTP_CODE_PATTERN = /Code:\s*(\d+)\s*--\s*Error:/
+
+          # Case-insensitive: HTTP header names are conventionally capitalised in a raw dump, but
+          # nothing here guarantees a subprocess's captured text preserves that casing exactly.
+          RETRY_AFTER_PATTERN = /Retry-After:\s*(\d+)/i
+
+          BASE_DELAY_SECONDS = 1.0
+          MAX_DELAY_SECONDS = 30.0
+
+          # One decision, after ONE attempt has already run and been captured.
+          Decision = Struct.new(:should_retry, :delay_seconds, :reason, keyword_init: true) do
+            def retry?
+              !!should_retry
+            end
+          end
+
+          class << self
+            # @param output [String] combined stdout+stderr from the attempt just completed.
+            # @param status [Process::Status, nil] `nil` when the subprocess itself could not be
+            #   spawned at all (see `run_wave.rb#execute`'s own `rescue StandardError` branch) --
+            #   treated as a hard failure, never retryable (nothing about a spawn failure is an
+            #   HTTP status).
+            # @param attempt [Integer] 1-based -- the attempt that JUST ran.
+            # @param max_attempts [Integer] total attempts allowed, INCLUDING the first -- so
+            #   `max_attempts: 3` permits at most 2 retries after the initial attempt.
+            # @return [Decision]
+            def decide(output:, status:, attempt:, max_attempts: 3)
+              return Decision.new(should_retry: false, delay_seconds: 0, reason: :ok) if status&.success?
+              if attempt >= max_attempts
+                return Decision.new(should_retry: false, delay_seconds: 0,
+                                    reason: :max_attempts_reached)
+              end
+
+              code = retryable_http_code(output)
+              return Decision.new(should_retry: false, delay_seconds: 0, reason: :not_retryable) unless code
+
+              delay = retry_after_seconds(output) || backoff_delay_seconds(attempt)
+              Decision.new(should_retry: true, delay_seconds: delay, reason: :"http_#{code}")
+            end
+
+            # @return [Integer, nil] the HTTP status code found in `output`, only when it is one
+            #   of {RETRYABLE_HTTP_CODES} -- `nil` for anything else (including a code that WAS
+            #   found but is not on the retryable list, e.g. a 400).
+            def retryable_http_code(output)
+              match = HTTP_CODE_PATTERN.match(output.to_s)
+              return nil unless match
+
+              code = match[1].to_i
+              RETRYABLE_HTTP_CODES.include?(code) ? code : nil
+            end
+
+            # @return [Integer, nil] the server-requested wait, in seconds, when a `Retry-After`
+            #   header value was captured in the output -- takes priority over the computed
+            #   backoff below when present (the server knows better than a guess).
+            def retry_after_seconds(output)
+              match = RETRY_AFTER_PATTERN.match(output.to_s)
+              match && match[1].to_i
+            end
+
+            # Bounded exponential backoff with FULL jitter (AWS Architecture Blog's own
+            # "Exponential Backoff And Jitter", the well-established shape): a uniform random
+            # pick in `[0, capped)`, `capped = min(BASE * 2**(attempt-1), MAX)`. Full jitter
+            # (not merely +/- a percentage) is deliberate -- it is what actually de-correlates N
+            # concurrent workers that all hit a 429 in the SAME instant (`--concurrency N`'s own
+            # reason to exist) from retrying in lockstep and re-triggering the same rate limit.
+            # @return [Float] seconds, `0 <= delay < capped`.
+            def backoff_delay_seconds(attempt)
+              capped = [BASE_DELAY_SECONDS * (2**(attempt - 1)), MAX_DELAY_SECONDS].min
+              rand * capped
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -62,19 +62,8 @@ module Eco::API::UseCases::GraphQL::Compat
   #   force.custom_script = new_script     → write the LISP script
   #   force.script                         → raw script content (alias)
   #
-  # Affected cases currently blocked (from multi_org_api survey, ~50% of all
-  # ooze cases):
-  #   act-gov:        5 x 20240130_act_*_case, rearrage_page_sites_case
-  #   briscoes:       remove_induction_sections, 310524_Briscoes_Remove_Tasks
-  #   chorus:         4 x audit_update cases
-  #   hcc:            update_enterprise_risk_case
-  #   lic:            update_life_cycle_force_case
-  #   mitre10:        rich_text_update, update_location_force, updating_template
-  #   npdc:           contractor_title_force, risk_titile_force, fix_title_syncing,
-  #                   reminder_date_fields, 10092024_NPDC_CP_Add_Force
-  #   profile-group:  int_training_review, 20231026_profile_wellness
-  #   turners-growers: event_changes, inj_cost_calc, remove_line_force
-  #   twg:            hide_attached_risks, add_new_force
+  # Affected cases currently blocked: roughly half of all ooze cases in the internal script repos'
+  # survey (per-customer breakdown kept in the internal migration notes, not in this gem).
   #
   # Implementation sketch (to be built when the endpoint lands):
   #

data/lib/eco/api/usecases/graphql/helpers/pages.rb

@@ -7,7 +7,7 @@ module Eco::API::UseCases::GraphQL::Helpers
   # with duck-typing so they work against the GraphQL page/section/field models.
   #
   # This is Phase 1 of the ooze -> native GraphQL migration (build the shared substrate before
-  # any case). See ecoportal-api-graphql/.ai-assistance/projects/ooze-graphql-native-migration/.
+  # any case). See the ecoportal-api-graphql repo's internal docs.
   module Pages
   end
 end

data/lib/eco/api/usecases/graphql/samples/pages/template/command_emitter.rb

@@ -115,8 +115,15 @@ module Eco::API::UseCases::GraphQL::Samples::Pages
         end
 
         # Select-field option. dataFieldId threads the (placeholder) field id.
-        def option(label:, weight: nil)
-          @emitter.emit(:addSelectFieldOption, data_field_id: @field_id, label: label, weight: weight)
+        #
+        # `value:` is a REQUIRED keyword -- the backend's AddSelectFieldOptionInput declares
+        # `argument :value, String, required: true`, and it is the option's unique key (cast to a
+        # number for numeric select fields). There is no default and it is never derived here from
+        # label/weight/position: a plausible-looking derived value would silently store WRONG data on
+        # exactly the scored fields this feature is used for. Callers must supply an explicit value.
+        def option(label:, value:, weight: nil)
+          @emitter.emit(:addSelectFieldOption, data_field_id: @field_id, label: label, value: value,
+                                               weight: weight)
           @field_id
         end
       end

data/lib/eco/api/usecases/graphql/samples/pages/template/csv_build/builder.rb

@@ -111,7 +111,7 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
           description: field.description
         ) do |field_builder|
           Array(field.options).each do |opt|
-            field_builder.option(label: opt[:label], weight: opt[:weight])
+            field_builder.option(label: opt[:label], value: opt[:value], weight: opt[:weight])
           end
         end
       end

data/lib/eco/api/usecases/graphql/samples/pages/template/csv_build/format_map.rb

@@ -15,8 +15,17 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
     #
     #   * `field_type`     — a template field type accepted by addField (e.g. plain_text, select,
     #                        date, number, gauge, rich_text, people, ...). Passed through verbatim.
-    #   * `field_options`  — for select-type fields: pipe-separated `label:weight` pairs,
-    #                        e.g. "High:10|Medium:5|Low:0". Weight optional ("High|Medium|Low").
+    #   * `field_options`  — for select-type fields: pipe-separated `label:value:weight`
+    #                        triples, e.g. "High:10:10|Medium:5:5|Low:0:0". `value` is the
+    #                        backend's unique, REQUIRED select-option key (cast to a number for
+    #                        numeric select fields) -- NEVER derived from label/weight/position
+    #                        here, because a derived value can collide (duplicates are rejected
+    #                        server-side) or silently store the WRONG number on a scored field.
+    #                        Weight optional via a trailing empty part, e.g. "High:H:|Low:L:". A
+    #                        cell resolving to exactly two parts (the OLD `label:weight`
+    #                        shorthand -- now ambiguous with a value-only `label:value`) or a
+    #                        bare label RAISES ArgumentError naming the field, option label, and
+    #                        offending cell -- see `#options` below.
     #   * `field_description` — carries the SECTION/FIELD IDENTITY convention (see below).
     #
     # SECTION / FIELD IDENTITY CONVENTION (per the CSV-pipeline project notes): stable identity for a
@@ -68,20 +77,50 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
           field_required:    truthy?(row, :field_required),
           field_column:      integer(row, :field_column) || 0,
           field_description: value(row, :field_description),
-          field_options:     options(value(row, :field_options))
+          field_options:     options(value(row, :field_options), field_label: value(row, :field_label))
         )
       end
 
-      # Parse the options cell into [ { label:, weight: }, ... ]. Empty → [].
-      def options(cell)
+      # Parse the options cell into [ { label:, value:, weight: }, ... ]. Empty → [].
+      #
+      # `field_label:` is ONLY used for the ArgumentError message below -- it identifies which field's
+      # options cell is malformed, since a builder raising mid-batch on a 500-row CSV is otherwise
+      # nearly impossible to trace back to the offending row.
+      def options(cell, field_label: nil)
         return [] if cell.nil? || cell.to_s.strip.empty?
 
         cell.to_s.split(OPTIONS_DELIMITER).map do |token|
-          label, weight = token.split(OPTION_WEIGHT_SEPARATOR, 2).map(&:strip)
-          { label: label, weight: (weight && !weight.empty? ? Integer(weight, exception: false) : nil) }
+          option_from_token(token, field_label: field_label, cell: cell)
         end
       end
 
+      # A token must resolve to exactly `label:value` or `label:value:weight` (weight optional, via a
+      # present-but-empty third part). Anything else -- a bare label, or exactly two parts -- means no
+      # explicit `value` was given. Because a `label:X` two-part cell is indistinguishable from the OLD
+      # `label:weight` shorthand, it is REJECTED rather than guessed at: see the module doc for why a
+      # derived value is worse than a loud failure.
+      def option_from_token(token, field_label:, cell:)
+        parts = token.split(OPTION_WEIGHT_SEPARATOR, 3).map(&:strip)
+        label = parts[0].to_s.empty? ? nil : parts[0]
+        value = parts[1]
+
+        if parts.size < 3 || value.nil? || value.empty?
+          raise ArgumentError, missing_option_value_message(field_label, label || token, cell)
+        end
+
+        weight_raw = parts[2]
+        { label: label, value: value,
+          weight: (weight_raw && !weight_raw.empty? ? Integer(weight_raw, exception: false) : nil) }
+      end
+
+      def missing_option_value_message(field_label, option_label, cell)
+        "select option is missing an explicit `value` (field: #{field_label.inspect}, " \
+          "option: #{option_label.inspect}, cell: #{cell.to_s.inspect}). The old `label:weight` " \
+          'two-part shorthand is no longer accepted -- addSelectFieldOption requires a unique, ' \
+          'non-derived `value` per option. Add one explicitly, e.g. ' \
+          "\"#{option_label}:VALUE\" or \"#{option_label}:VALUE:WEIGHT\"."
+      end
+
       def value(row, logical)
         header = COLUMNS.fetch(logical)
         raw    = row[header]

data/lib/eco/api/usecases/graphql/samples/pages/template.rb

@@ -1,6 +1,6 @@
 module Eco::API::UseCases::GraphQL::Samples::Pages
   # Template (workflow) build-from-scratch + (later) diff-and-update samples.
-  # See ecoportal-api-graphql/.ai-assistance/projects/template-maintenance/.
+  # See the ecoportal-api-graphql repo's internal docs.
   module Template
   end
 end

data/lib/eco/language/klass/auto_loader.rb

@@ -21,9 +21,18 @@ module Eco::Language::Klass
 
       pending_children.each do |klass|
         @child = klass.new(object)
-      rescue TypeError => _e
-        # Can't create from this class (must be the singleton class)
-        # Just ignore
+      rescue StandardError => _e
+        # Can't create from this class (must be the singleton class), OR the class was
+        # never fully configured for a real registration -- e.g. an anonymous
+        # `Class.new(SomeAutoloadedBase)` test double left behind, un-configured, by an
+        # ENTIRELY UNRELATED spec elsewhere in the same process (this scan walks
+        # `ObjectSpace`, a process-wide, cross-spec-file concern -- see
+        # `spec/eco/language/klass/auto_loader_spec.rb`'s own "malformed pending child"
+        # example, and `spec/support/fakes/c7_person_entry_fakes.rb`'s header, for two
+        # already-documented instances of this exact class of fragility). Best-effort
+        # discovery: one malformed/unrelated pending child must never abort loading the
+        # REST of the pending children, still less raise into a caller that has nothing
+        # to do with it. Just ignore, same as the original TypeError case above.
       ensure
         autoloaded_children.push(klass)
       end

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.3.1'.freeze
+  VERSION = '3.4.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: 3.4.0
 platform: ruby
 authors:
 - Oscar Segura
@@ -259,20 +259,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: ecoportal-api-v2
   requirement: !ruby/object:Gem::Requirement
@@ -713,6 +713,8 @@ files:
 - lib/eco/api/session/batch/policies.rb
 - lib/eco/api/session/batch/searcher.rb
 - lib/eco/api/session/batch/status.rb
+- lib/eco/api/session/concurrency/bounded_worker_pool.rb
+- lib/eco/api/session/concurrency/retry_policy.rb
 - lib/eco/api/session/config.rb
 - lib/eco/api/session/config/api.rb
 - lib/eco/api/session/config/apis.rb
@@ -731,7 +733,6 @@ files:
 - lib/eco/api/session/config/tagtree.rb
 - lib/eco/api/session/config/workflow.rb
 - lib/eco/api/usecases.rb
-- lib/eco/api/usecases/CLAUDE.md
 - lib/eco/api/usecases/base_case.rb
 - lib/eco/api/usecases/base_case/model.rb
 - lib/eco/api/usecases/base_case/type.rb
@@ -818,7 +819,6 @@ files:
 - lib/eco/api/usecases/default_cases/update_case.rb
 - lib/eco/api/usecases/default_cases/upsert_case.rb
 - lib/eco/api/usecases/graphql.rb
-- lib/eco/api/usecases/graphql/CLAUDE.md
 - lib/eco/api/usecases/graphql/base.rb
 - lib/eco/api/usecases/graphql/compat.rb
 - lib/eco/api/usecases/graphql/compat/ooze_redirect.rb
@@ -829,7 +829,6 @@ files:
 - lib/eco/api/usecases/graphql/compat/parity/harness.rb
 - lib/eco/api/usecases/graphql/compat/parity/run_result.rb
 - lib/eco/api/usecases/graphql/helpers.rb
-- lib/eco/api/usecases/graphql/helpers/CLAUDE.md
 - lib/eco/api/usecases/graphql/helpers/access_logs.rb
 - lib/eco/api/usecases/graphql/helpers/access_logs/base.rb
 - lib/eco/api/usecases/graphql/helpers/access_logs/base/reader.rb
@@ -879,7 +878,6 @@ files:
 - lib/eco/api/usecases/graphql/helpers/pages/shortcuts.rb
 - lib/eco/api/usecases/graphql/helpers/pages/typed_fields_pairing.rb
 - lib/eco/api/usecases/graphql/samples.rb
-- lib/eco/api/usecases/graphql/samples/CLAUDE.md
 - lib/eco/api/usecases/graphql/samples/contractors.rb
 - lib/eco/api/usecases/graphql/samples/contractors/dsl.rb
 - lib/eco/api/usecases/graphql/samples/location.rb
@@ -907,7 +905,6 @@ files:
 - lib/eco/api/usecases/graphql/samples/location/service/tree_to_list/converter/parser.rb
 - lib/eco/api/usecases/graphql/samples/location/service/tree_to_list/output.rb
 - lib/eco/api/usecases/graphql/samples/pages.rb
-- lib/eco/api/usecases/graphql/samples/pages/CLAUDE.md
 - lib/eco/api/usecases/graphql/samples/pages/org_page.rb
 - lib/eco/api/usecases/graphql/samples/pages/org_page/base.rb
 - lib/eco/api/usecases/graphql/samples/pages/org_page/dsl.rb

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

@@ -1,78 +0,0 @@
-# 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/graphql/CLAUDE.md

@@ -1,120 +0,0 @@
-# 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/helpers/CLAUDE.md

@@ -1,79 +0,0 @@
-# usecases/graphql/helpers
-
-Mixin modules providing domain-specific helper methods for GraphQL use cases.
-All modules are ultimately included via `Helpers::Base` into `GraphQL::Base`.
-
----
-
-## Include chain
-
-```
-GraphQL::Base
-    includes Helpers::Base
-        includes CaseEnv        → session, options, config, simulate?, log, ErrorHandling
-        includes GraphQLEnv     → graphql (lazy, memoized)
-    includes Helpers (loader)
-        includes Helpers::Location      → location tree helpers
-        includes Helpers::Contractors   → contractor entity helpers
-```
-
----
-
-## Helpers::Base (`helpers/base.rb`)
-
-Core environment — included in every GraphQL use case.
-
-| Method | Source | Description |
-|--------|--------|-------------|
-| `session` | `CaseEnv` | Current `Eco::API::Session` |
-| `options` | `CaseEnv` | Options hash from CLI/runner |
-| `config` | `CaseEnv` | `session.config` shortcut |
-| `simulate?` | `CaseEnv` | `options[:simulate] \|\| options[:dry_run]` |
-| `log(level)` | `CaseEnv` | Logger proxy |
-| `graphql` | `GraphQLEnv` | Lazy-loaded `Ecoportal::API::GraphQL` instance |
-| `backup(data, type:)` | `Helpers::Base` | Save JSON to requests folder |
-| `exit_error(msg)` | `Helpers::Base` | Log error and `exit(1)` |
-
----
-
-## Helpers::Location (`helpers/location/`)
-
-Location tree access, tag remapping, classification parsing.
-
-- `helpers/location/base.rb` — `Location::Base` mixin
-- `helpers/location/base/tree_tracking.rb` — track tree mutations
-- `helpers/location/base/classifications_parser.rb` — parse location classifications
-- `helpers/location/tags_remap/` — remapping tags across location changes
-- `helpers/location/command/` — apply/diff location structure commands
-
----
-
-## Helpers::Contractors (`helpers/contractors/`)
-
-Contractor entity loading helpers.
-
-- `helpers/contractors/base.rb` — base contractor helpers
-- `helpers/contractors/base/load.rb` — batch load contractor entities
-
----
-
-## Adding a new helper
-
-1. Create `helpers/my_domain/base.rb`:
-   ```ruby
-   module Eco::API::UseCases::GraphQL::Helpers
-     module MyDomain
-       module Base
-         private
-         def my_helper_method
-           graphql.myDomainQuery(...)
-         end
-       end
-     end
-   end
-   ```
-2. Create `helpers/my_domain.rb` as a loader that includes `Base`
-3. Add `require_relative 'my_domain'` to `helpers.rb`
-
-The helper is then available in all cases that include `Helpers::Base` (i.e., all
-subclasses of `GraphQL::Base` including `PageCase` and `OrgPageCase`).

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

@@ -1,76 +0,0 @@
-# usecases/graphql/samples
-
-Built-in GraphQL sample base classes shipped with the gem.
-These are abstract/semi-abstract classes that org scripts inherit from.
-Concrete, CLI-integrated cases go in `usecases/default/` instead.
-
----
-
-## Hierarchy convention
-
-Each domain follows:
-```
-samples/<domain>.rb              ← namespace loader (may also BE the base class)
-samples/<domain>/
-  <level>/
-    dsl.rb                       ← DSL concern — include in base, available to subclasses
-    base.rb                      ← Base class (inherits from GraphQL::Base or parent level)
-    <functional_level>.rb        ← Optional: opinionated subclass, inherit directly
-    <functional_level>/
-      dsl.rb                     ← Further DSL for that functional level
-```
-
-DSLs are always **concerns (modules)** to include — never classes.
-Bases are **classes** with the scaffolding logic.
-Functional levels add opinionated defaults on top of base.
-
----
-
-## Contents
-
-| File | Class | Purpose |
-|------|-------|---------|
-| `samples/location.rb` | `Samples::Location` | Location structure management |
-| `samples/location/command.rb` | `Samples::Location::Command` | Apply location tree commands |
-| `samples/location/service.rb` | `Samples::Location::Service` | Tree diffing and conversion service |
-| `samples/contractors.rb` | `Samples::Contractors` | Contractor entity base case |
-| `samples/contractors/dsl.rb` | `Contractors::DSL` | Contractor helper mixin |
-| `samples/pages.rb` | `Samples::Pages` (namespace) | Page processing cases loader |
-| `samples/pages/page/dsl.rb` | `Pages::Page::DSL` | SearchConf helpers mixin |
-| `samples/pages/page/base.rb` | `Pages::Page::Base` | Register-scoped page iteration |
-| `samples/pages/org_page/dsl.rb` | `Pages::OrgPage::DSL` | Org-page DSL (extends Page::DSL) |
-| `samples/pages/org_page/base.rb` | `Pages::OrgPage::Base` | Org-wide page iteration |
-
----
-
-## Difference: samples vs org-specific cases vs default
-
-| Layer | Location | Purpose |
-|---|---|---|
-| **samples** (here) | `eco-helpers/lib/.../graphql/samples/` | Abstract base classes — org scripts inherit |
-| **default** | `eco-helpers/lib/.../usecases/default/` | Concrete CLI-integrated cases for ALL orgs |
-| **org-specific** | `multi_org_api/{org}/config/graphql_cases/` | Org-specific implementations |
-
-Org scripts inherit from `samples/`, optionally via `default/` as an intermediate layer.
-
----
-
-## Adding a new built-in sample
-
-1. Create the case file in `samples/`:
-   ```ruby
-   # lib/eco/api/usecases/graphql/samples/my_domain.rb
-   class Eco::API::UseCases::GraphQL::Samples::MyDomain < Eco::API::UseCases::GraphQL::Base
-     name 'my-domain-case'
-     type :other
-
-     def process
-       # ...
-     end
-   end
-   ```
-
-2. Add `require_relative 'samples/my_domain'` to `samples.rb`.
-
-If the case is page-centric, inherit from `PageCase` instead of `Base` to get
-pagination, KPI tracking, and `update_page` for free.

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

@@ -1,59 +0,0 @@
-# samples/pages
-
-Base classes for GraphQL-native page processing use cases.
-
----
-
-## Structure
-
-```
-pages/
-  page/
-    dsl.rb          ← Page::DSL — SearchConf helpers mixin (sc, in_register, state_is, ...)
-    base.rb         ← Page::Base — register-scoped page iteration + KPI scaffolding
-  org_page/
-    dsl.rb          ← OrgPage::DSL — extends Page::DSL (org-wide helpers)
-    base.rb         ← OrgPage::Base — org-wide iteration (no default register scope)
-```
-
----
-
-## Inheritance
-
-```
-GraphQL::Base
-    ↓
-Samples::Pages::Page::Base          (register-scoped, inherits Page::DSL)
-    ↓
-Samples::Pages::OrgPage::Base       (org-wide, overrides search_conf)
-    ↓
-your org subclass
-```
-
----
-
-## Page::Base — register-scoped scripts
-
-Override `process_page(page)` and optionally `search_conf`.
-Set `register_id` and `batch_size` on the class.
-
-## OrgPage::Base — org-wide scripts
-
-Same as Page::Base but `search_conf` starts empty.
-Add your own filters via `super.filter(state_is(:active))` etc.
-
----
-
-## Adding a functional level
-
-If a common pattern emerges (e.g., "stage-submit scripts"), add:
-
-```
-pages/page/
-  stage_submitter.rb          ← Page::StageSubmitter < Page::Base
-  stage_submitter/
-    dsl.rb                    ← StageSubmitter::DSL
-```
-
-Keep base.rb for the pure iteration scaffolding; put opinionated defaults in
-the functional level so scripts can choose their entry point.