ecoportal-api-graphql 2.0.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e679d934d9305d1926abe7251617eea0e5333c04665672b25f5ad38afb67d9b3
-  data.tar.gz: 2b8047d56b9af371b71308bcabce23f8e4c4b67d014ce7a4095386fadb1f89f4
+  metadata.gz: 128e83d1aa8d0fa5b9e4ce95f8bbd5f8bd4f219ea7d7a94dd18ec31225ac3ce9
+  data.tar.gz: 7d79138b320e6ba09221bd79a4c341ef9dc039f4ccf6923567f3f4b36f657c27
 SHA512:
-  metadata.gz: 6ec6f2792de809534943497a98a74ec012b061778d379bb9f8ac205805cd9a629386c3293ee00e647549564fed5edbbc80e73cf856340922548309b8e9c68435
-  data.tar.gz: 948f0064aa886e310fc24f78a3919cbccc3b192495c724d86d003e1ff03bd39d2d12b312e82c04ca6626779abd822f9f9914de44b651c4903ba51d275085f7e8
+  metadata.gz: 04cb9487e78e2f11b4c71572bc17915570a8638da67df94cfa27f0dfb3400d2c9f67bcaf25ac1b5bb61f86f1884f5af88b3adf961528ef8d3e5567607fcc1140
+  data.tar.gz: 3036e3e2295a5a2eb5876e66b145d09f3fd1a96fc174234f77621b0cd553ad2e501dc4d9c1baf74077990d9ed03c77e9bb8c8858cec97005e7dbefbeb05bda45

data/CHANGELOG.md

@@ -2,7 +2,391 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [2.2.1] - 2026-09-30
+
+### Security
+
+- Security republish of `2.2.0` -- backwards-compatible: removes customer and internal identifiers
+  from shipped comments and this changelog. Packaging is unchanged: `2.2.0` already shipped only
+  allowlisted files (`lib/**/*.rb` plus the named root docs).
+
+### Fixed
+
+- **Fixed:** `api.permissions` (`Query::Permissions`) failed against live after the 2026-09-29
+  platform release, which removed `Permissions.pageSmartAssistantCanChat` and
+  `Permissions.registerAssistantCanChat` (smart-assistant consolidation). `Fragment::Permissions` no
+  longer selects them. The model accessors are kept, deprecated, and now always return `nil`, so
+  callers do not break. Affects every earlier version, including 2.2.0.
+
+### Added
+
+- **Added:** `WorkflowCommand` builder for `moveSectionToStage` (new in the 2026-09-29 live schema):
+  `build(:moveSectionToStage, source_stage_id:, target_stage_id:, section_id:, anchorId:, anchorPosition:)`,
+  moving an existing section to another stage. `anchorPosition` is validated like the other anchor commands.
+
+## [2.2.0] - 2026-09-02
+
+★ **This release supersedes 2.1.0, which was version-bumped and changelogged on 2026-08-21 but never
+tagged or published** — RubyGems' highest was still 2.0.0. Do not go looking for 2.1.0; it does not
+exist as a gem. Its contents are included below by inheritance (they were already on `main`), and
+2.2.0 adds what landed after that bump. Publishing the 2.1.0 artifact would have shipped a state
+already superseded by merged `lib/` fixes and required a second release immediately.
+
+**Minor, not patch:** `Input::WorkflowCommand::AddSelectFieldOption.build` now REQUIRES a `value:`
+keyword. Under the versioning convention (minor = breaking, patch = compatible) that is breaking,
+even though the omitted argument meant the old call shape was already rejected by the server — a
+caller adapting to this is changing working-looking code.
+
+### Added
+
+- `tools/template_yaml/yaml_to_raw_json.py` -- a small, self-contained YAML-to-raw-JSON bridge
+  (inlines the BSON-aware `EpLoader`/`load_dump` the retired Python projector used) so a template
+  backup YAML attached to a ticket can still be fed to the Ruby CLI, which only ever reads JSON.
+  Drops `update_histories` by default (churn neither projector read, and a recurring source of
+  corrupted ObjectIds), with `--keep-churn` to keep it.
+
+
+- **`Page#all_tags` / `Stage#all_tags` read side** (`Model::Page::Phased`, `Base::Page::Phased::Stage`,
+  `Interface::BasePage`): the compiled tag set for a page or a single stage, folded client-side from
+  the page's `baseTags` and the stage's own tags, with both fetched by the page fragments
+  (`Fragment::Page`, `Fragment::Pages::CommonPageUnion`). `Stage#page` now resolves through the
+  native `DoubleModel` root reference rather than a hand-rolled back-pointer, and `location_ids`
+  is redirected page -> stage accordingly.
+
+  ★ This code was written on 2026-07-06 and then sat on three unmerged local branches for seven
+  weeks. `main` never received it in any form, and no other trace of it exists in history --
+  deleting those branches during a sweep would have lost a spec-covered feature permanently. It is
+  cherry-picked here onto current `main` rather than merged from the branch: `main` has since
+  changed four of the five files involved, so taking the branch's copies wholesale would have
+  reverted shipped fixes. That is the stranded-work failure mode this repo has a root-cause note
+  about, caught this time only because a branch sweep asked what each unmerged branch actually
+  contained.
+
+- `tools/template_yaml/forces_walker.rb`: Ruby port of the template projector's `project_forces` /
+  `script_identifiers` (P4), classifying each binding as a FIELD or a SECTION target rather than
+  conflating the two, and reporting the unread force-level `globalBindings` gap as unverified
+  instead of as a finding. Gated by `tools/template_yaml/compare_forces.rb` against the Python IR.
+
+- `tools/template_yaml/review.rb` / `update_gate.rb`: Ruby port of the template projector's
+  `review` / `update_gate` (P5), refusing a template's bulk update PER TEMPLATE (not per field)
+  when no field carries a usable identifier or identifiers are non-unique. Adds a Ruby-only
+  `ximport` tooltip guard: fields marked exclude-from-import are counted and protected, never
+  treated as overwritable. `Delta.call`'s `reviewer:` seam is now wired to `Review.method(:call)`,
+  so `review_findings` appears in the delta payload. Gated by `tools/template_yaml/compare_gate.rb`
+  against a customer's 18 templates -- refusal set matches the Python exactly.
+
+- `tools/template_yaml/model.rb`: Ruby port of the template projector's `project(doc, source)` 
+  (P3's IR assembly), composing field and force walks into a compact IR dict with key order
+  matching the Python prototype for P8 differential acceptance.
+- `tools/template_yaml/render_markdown.rb`: Ruby port of `render_markdown(model, findings)` (P7),
+  rendering a template and its review findings as Markdown with all Python quirks reproduced
+  verbatim: the dead `stage` column, escape-then-truncate on `label`, redundant `type` re-split,
+  CRLF-to-LF normalization on force scripts, and preserved literals like `'(unnamed)'`,
+  `'(no custom script)'`, `'(none)'`.
+- `tools/template_yaml/cli.rb`: Ruby CLI entrypoint matching Python's `main()` (P7), supporting
+  single-file and directory modes, `--out`, `--json`, and `--delta` flags. **Input is JSON 
+  (`*.json`), not YAML**, per Loader's design (see loader.rb header). File writes are LF-only
+  on all platforms via binary mode. Directory mode processes `*.json` files alphabetically,
+  accumulates an `_index.md` at the end, and leaves earlier files on disk if an error occurs
+  mid-run (no transactional cleanup).
+
+- `tools/template_yaml/differential_gate.rb`: P8, the template-yaml Ruby port's acceptance gate.
+  Regenerates BOTH IRs fresh in one run -- Ruby in-process (`Loader` -> `Model.build` -> `Review`
+  -> `UpdateGate`) over the `*.json` corpus, Python via a single batched subprocess (direct
+  import of `ep_template_yaml.py`, not its CLI) over the `*.yaml` corpus -- and diffs the ENTIRE
+  IR: every template attribute, every field, every force (incl. bindings), every review finding,
+  and the `update_gate` refusal set. Live run over a customer's 18 templates: **`P8 GATE: PASS`**,
+  0 unexpected divergences, 12 expected (the six known-corrected ObjectIds, each seen twice --
+  once as a field id, once as a binding `reference_id`).
+- `tools/template_yaml/known_divergences.rb`: the six-id whitelist and its `corrupted_id?` rule,
+  extracted out of `compare_fields.rb` so P3's gate and the new P8 gate share one definition
+  instead of two copies drifting apart.
+- Fixed a Ruby port defect in `review.rb`, found live by the P8 differential run: finding
+  `detail` text quoted force/binding/field names with Ruby's `String#inspect` (always
+  double-quoted) where the Python source uses `%r` (CPython `repr()`, single-quoted by
+  default). Added `Review.py_repr` to reproduce Python's exact quoting.
+- Excluded `patch_ver` and `updated_at` from P8's template-attribute comparison, alongside the
+  pre-existing `source_file` exclusion: the `templates_yaml`/`templates_json` fixture corpora
+  under `tmp/mns_01_tooltip_update/` are two separate exports pulled two days apart (confirmed
+  by file mtime), so these two pass-through fields legitimately disagree -- a corpus-provenance
+  artifact, not a port defect. `compare_fields.rb` / `compare_forces.rb`'s existing 0-unexpected
+  results already proved field/force content is identical across the two pulls.
+
+### Changed
+
+- **Changed** what a failing query prints. `Logic::BaseQuery`'s rescue used to `pp kargs` /
+  `pp query_params` / `pp block` to **stdout** on every error. That existed for a real reason —
+  graphlient masks the origin, so it was the only way to see which query failed — but it put GraphQL
+  variables (page ids, emails, field values) on stdout and into CI logs. Ruby populates `.cause` when
+  raising inside a rescue, so the original error keeps the source location `graphql-client`
+  deliberately sets: the report now names `err.cause`'s class and **the failing query's own source
+  location** on **stderr**, which is more of what the dump was for. Variables are emitted only when
+  the client's existing `deep_logging` flag is on; `pp block` is dropped. A blank message (which
+  graphlient's `GraphQLError#to_s` can render) is now labelled instead of printing nothing.
+  Tracked as Q-43.
+
+### Fixed
+
+- **Fixed** `currentOrganization.pageActivities` returning nothing. The wiring in
+  `Model::Organization` injected `base_path: ['currentOrganization']`, which overrides the
+  `base_path 'currentOrganization.page'` declared by `Query::PageActivities` — so the client
+  dug `currentOrganization.activities`, a path the emitted document never contains (the
+  inline-fragment `activities` merges into `page`). Added `subpath: 'page'`, plus a spec that
+  compares every wired query's declared base_path against the one the wiring injects, so the
+  whole class of bug is guarded rather than the one instance. Tracked as Q-13.
+
+- **Fixed** `Common::GraphQL::ResponseError` discarding `errors[].extensions`. It now carries the
+  raw error entries and exposes `#errors`, `#extensions`, `#codes`, `#details`, `#full_messages`
+  and `#unauthorized?`. This is what makes a permission problem distinguishable from a request
+  problem in Ruby — the diagnosis a customer integration pack tells customers to perform, which until now no tool
+  built on this gem could actually follow. The message still LEADS with the joined server messages
+  (existing matchers keep working) and appends `code:` / `details:` after them. `tools/<customer>/cli.rb`
+  now reports the server's own classification instead of sniffing the message for `/unauthoriz/i` —
+  a sniff that could not tell a policy refusal from a FIELD-level gate. Tracked as Q-27.
+
+- **Fixed** `Payload::Kickstand::BulkUpdateJobs` and `BulkUpdateWorkflows` raising `NoMethodError`
+  on `#items` and `#errors`. Both called `from_doc`, which is a per-class convention in this gem
+  (only 7 classes define one) and does not exist on `Base::Kickstand::Job`/`Workflow` or on
+  `Error::ValidationErrors`. Any caller reading the result of a Kickstand bulk update crashed.
+  Replaced with the real constructor, `new(doc)`. These two classes had **no spec of any kind** —
+  that is why it shipped — so this adds the missing coverage (12 examples over both, shared) as
+  well as the guard. Found while mapping the client's failure surface for Q-31.
+
+- **Packaging allowlist is now keyed on the full path, not the root directory.** `spec.files`
+  previously allowed anything under `lib/` or `exe/`, which packaged five `CLAUDE.md`
+  agent-instruction files living inside `lib/` (573 files now ship, down from 578). The
+  publish-time gate in `scripts/release_smoke_check.rb` had the same hole -- it exempted `lib/`
+  wholesale, so it could not see them by construction. Both now require every packaged path to
+  match `lib/**/*.rb`, `exe/*`, or one of the three named root docs, and the rule is pinned by
+  `spec/packaging_spec.rb` (15 examples, including one that proves the excluded files remain
+  tracked in the repo). No credentials or customer data were ever affected.
+
+- **Seven workflow-command input builders were silently discarding arguments the backend accepts.**
+  Each builder filters its keyword arguments through an allowlist with `kwargs.slice(*KEYS)`, so a
+  key missing from the allowlist is dropped before the request is built: no error, no warning, no
+  effect. The mutation succeeds and does nothing.
+
+  | command | argument restored |
+  |---|---|
+  | `addSelectFieldOption` | `value` — ★ `required: true` on the backend, so **every call this builder produced was rejected by the server** |
+  | `editSelectFieldOption` | `value` |
+  | `editFieldConfiguration` | `required`, `hiddenOnReports` |
+  | `editTemplateBasicSettings` | `enableCopyPage` |
+  | `EditFieldConfiguration::PlainText` | `multiline` |
+  | `EditFieldConfiguration::ContractorEntities` | `applyPermissionsToParent` (distinct from `applyAttachedContractorsPermissionsTo`, which was already present) |
+  | `editForce` | `lastSyncedAt` |
+
+  Found by comparing all 123 command-bus inputs against the backend Rails source rather than
+  against the gem's stored introspection snapshot — that snapshot is dated 2026-07-30, does not
+  show these arguments, and would have confirmed the wrong answer. 104 commands were verified
+  clean. Every restored key is now pinned by a spec asserting on the OUTPUT of `build`, and three
+  of the affected classes had no spec file at all before this, which is a large part of how the
+  drift survived.
+
+- **`Diff::Change` and the template-builder options DSL now carry an option's `value`.** Making
+  `value` required on `AddSelectFieldOption.build` exposed that two production paths never had one:
+  `Builder::TemplateBuilder#emit_options` and `Diff::CommandSynthesizer#option_command`. Neither had
+  ever been able to emit a valid `addSelectFieldOption`; the specs that passed were pinning a
+  command shape the server rejects. `VersionDiff#index_options` now captures `o['value']` alongside
+  label and weight — the field was already being fetched by the page-content fragment and thrown
+  away by the diff layer. Where no value is available, both paths **raise** naming the option and
+  field: `value` is documented as cast to a number for numeric select fields, so defaulting it to
+  the label would silently store wrong data on precisely the scored fields that matter.
+
+- Corrected a false comment in `add_field.rb` asserting that a field's `required` flag "cannot be
+  persisted through the workflow command bus at all". It can, via `editFieldConfiguration`. A
+  comment stating a platform limitation that does not exist is worse than no comment: it stops
+  people trying.
+
+### Removed
+
+- `tools/template_yaml/ep_template_yaml.py` and `tools/template_yaml/mns_review.py` -- the
+  original Python template-backup projector and its cross-template audit. P9 of the template-yaml
+  Ruby port: the Ruby port (`model.rb`, `review.rb`, `update_gate.rb`, `render_markdown.rb`,
+  `cli.rb`) was proven byte/field-parity-identical to both by the P8 differential gate
+  (`differential_gate.rb`, 0 unexpected divergences over 18 live templates) before removal, and
+  the last remaining live use case -- a Jira ticket's YAML-only attachment (EPT-1872) -- was
+  re-verified against the promoted bridge (`yaml_to_raw_json.py`) with byte-identical
+  Python/Ruby deltas. Recoverable in full: `git show
+  0caa6f3d80c6495a9f92132178b9a6a42deb40f5:tools/template_yaml/ep_template_yaml.py` (and the same
+  path for `mns_review.py`).
+
+## [2.1.0] - 2026-08-21
+
+Everything accumulated on `main` since `v2.0.0` (2026-08-13): 150 commits touching 73 files under
+`lib/`. **Minor, not patch:** the bulk is additive -- new data-field models, the last command-bus
+command, a native people-directory query, template-change-log reading -- and 73 library files is not
+a patch by any honest reading. **Minor, not major:** no surface was removed or reshaped, so `~> 2.0`
+consumers adopt it without a floor change.
+
+★ Why this release exists at all, beyond the contents: a remote clone installs PUBLISHED gems, so
+until this went out none of that work could reach the api runner -- and `main` could not be released
+either, because its version constant still read `2.0.0`, which `rake release:check` correctly refuses
+as already published. Three weeks of library work with no route to a remote is the failure mode this
+closes.
+
+
+### Added
+
+- **Wired the `manageCopyPageConfiguration` workflow command** (`Input::WorkflowCommand::ManageCopyPageConfiguration`,
+  first observed in the live schema 20260819): controls `overridePageCreatorPermissions`,
+  `autoIncludeNewContent`, and per-data-field `inclusionSettingsChanges` (`dataFieldId` /
+  `include` / `enforce`) for copy-page behaviour. Closes the last gap in the command bus --
+  `validate-queries` now reports 106/106 commands wired.
+
+- `tools/<customer>/collection.rb` -- a pure-Ruby, stdlib-only read interface over a customer's Postman "ALL
+  CASES" master collection (the sibling `ep-api-collections` repo masters it; this gem never
+  hand-copies its knowledge). Walks the folder tree, exposes each GraphQL request's full path,
+  name, query, parsed variables, and `{{placeholder}}` inventory, with a name/path lookup that
+  tolerates a folder-path prefix and raises a named error listing near-matches when nothing
+  resolves. `spec/tools/<customer>/collection_sync_spec.rb` pins the webhook-admin and build/update-page
+  request paths plus the placeholders the tooling depends on, and fails -- naming exactly what
+  disappeared -- if the collection renames or removes one of them; it skips cleanly (not fails)
+  when no sibling checkout is present. See `tools/<customer>/README.md`.
+
+- `tools/template_yaml/mns_review.py` -- cross-template audit over a directory of IR projections:
+  identifier coverage, `templateContainerUid` uniqueness and name plausibility, findings by code,
+  authoring-maturity signal, and classification of orphaned force bindings into projector gaps
+  versus real defects (checked against the source dumps). First run recorded in
+  `tools/template_yaml/reviews/2026-08-09-<customer>-18-templates.md`.
+
+- **`tools/<customer>/cli.rb`** -- a Ruby CLI that creates/lists/destroys a customer's webhook
+  subscription and verifies the setup read-only, runnable from a support server with nothing
+  but `USER_EMAIL`/`USER_PASS` supplied (every other value defaults to a customer UAT org, EU
+  instance). `webhook create` is idempotent in practice: it lists first and reports the
+  existing subscription instead of creating a duplicate when one already matches the URL and
+  template(s). `--dry-run` prints the GraphQL document and variables with no network call.
+  Document builders live in `tools/<customer>/webhooks.rb` (`<Customer>Webhooks::Documents`) as pure
+  functions, spec'd in `spec/tools/<customer>/webhooks_spec.rb` with no network involved.
+
+- **`Query::PersonMembers`** — the GraphQL-native people-directory path over
+  `organization.personMembers`, filling the gap flagged in `model/organization.rb`. Salvaged
+  from a stranded July branch (`feat/scim-apiv0-adapter-design`) whose SCIM design and
+  scaffold were superseded by the `ecoportal-scim` gem's `apiv0-people-adapter` project; this
+  query was the only part of it with no equivalent anywhere. ★ It is NOT the SCIM-sourced
+  People replacement for the APIv0 retirement — that port lives in `ecoportal-scim`.
+  Reuses the existing `Base`/`Model`/`Connection::PersonMember` classes; no new models.
+
+- `scripts/release_smoke_check.rb` — pre-push gate for BUILT gem artifacts (any gem in the
+  stack): packaging allowlist, byte corruption (`\r\r`, BOM, mixed EOL), and corruption-class
+  parse warnings via `ruby -wc`. Proven against real defects: red on eco-helpers 3.2.21
+  (shipped `\r\r\n`) and on the first 3.2.22 build (CHANGELOG `\r\r` via autocrlf smudge),
+  green on the corrected artifacts. Run it on every `.gem` before `gem push`.
+
+- **Template change log now reports WHAT changed**, not only who/when/which-resource. New
+  registered fragment `:TemplateChangeLogEntryDetail`, opt-in via
+  `api.template.change_log(id:, first:, detail: true)` or
+  `&Query::TemplateChangeLog.detail_block`. The default selection is unchanged and still light —
+  the common "who touched this template and when" read does not pay for per-type detail.
+  `Base::Template::ChangeLogEntry` gains `#changes`, `#changeMessages`, `#detail_kind`
+  (`:changes` / `:change_messages` / `:es_changes` / nil) and `#detail?`.
+  ★ The three concrete command types report changes in three different shapes, so `#changes`
+  returns raw hashes rather than a typed embed that would have to lie about one of them:
+  `PagesWorkflowCommandChange.changes` is `{field, from, to}` with STRING values;
+  `PagesWorkflowCommandEsChange.changes` has `from`/`to` as `StoredEsFilterType` OBJECTS (only
+  `field` is selected, so an ES change names which filter moved, not its before/after);
+  `PagesWorkflowCommandChangeMessage` carries pre-rendered `changeMessages` and no field/from/to.
+  Branch on `#detail_kind`. ★ Empty readers mean NOT SELECTED, never "nothing changed".
+
+- **Template change log (GraphQL-native)** — `Query::TemplateChangeLog` reads the platform's
+  per-change audit log for a template: "for template X, who changed what and when", newest first,
+  paginated. Reachable as `api.template.change_log(id: template_page_id, first: 50)`, or bare
+  (`api.template.change_log.each(id: …)`) for an auto-paginating enumerator.
+  Read path: `currentOrganization.page(id:) → template → commands` — `template` is declared on
+  `BasePageInterface`, so it is selected through a type condition (selecting on the returned
+  `PageUnion` directly is invalid GraphQL). New supporting types:
+  `Base::Template::ChangeLogEntry`, `Model::Template::ChangeLogEntry` (adds the `owner` embed —
+  WHO changed it), `Connection::TemplateChangeLog`, and the registered fragment
+  `:TemplateChangeLogEntry` on the interface `PagesWorkflowCommandInterface`.
+  ★ Two access caveats, both silent and both documented on `Base::Template::ChangeLogEntry`:
+  (1) the connection is **nil, not empty**, unless the caller satisfies
+  `Pages::TemplatePolicy#update_information?` — a read-only account sees no log and no error, so
+  never read nil as "nothing changed"; (2) the server scope is `from_template_builder`, so only
+  `TEMPLATE_BUILDER`-sourced commands appear — `WORKFLOW_BUILDER` changes to the same page are
+  excluded (those are on `Query::PagesWorkflowCommands`).
+  ★ Why this beats polling a watermark: a forces run writes with `skip_patch_incr` + `timeless`,
+  bumping **neither `patchVer` nor `updatedAt`** — any watermark-polling change tracker is blind to
+  force-driven change, whereas the command log is per-change. (Open: whether forces run against
+  templates specifically is not confirmed.)
+  Also documented in the repo's internal docs.
+
+- **New tool `tools/template_yaml/delta.rb`** (P6 of the template-YAML-tooling Ruby port): the
+  deterministic before/after difference between two `project()` snapshots, shaped for the Rovo
+  delta-verification agent. Field pairing on id-then-identifier (so a REBUILT field -- new id,
+  same `description` -- is one `changed` entry rather than an add/remove pair), `TRACKED`-only
+  attribute diffing, force diffing by name with binding set-difference, the five-key template
+  diff, and the four `not_evaluable` strings reproduced VERBATIM, because the Rovo agent is
+  instructed to read that list literally and any wording drift changes what it is told it cannot
+  verify. **Verified against the canonical Python on the known pre/post pair (all 7 comparable
+  sections identical) and on 9 synthetic scenarios covering every branch -- rebuild, removal,
+  untracked-only change, template attributes, force add/remove/script/binding-set-diff, and
+  reference-id-only binding moves -- 0 mismatches.**
+- **`Delta::Result` reports what the pairing could not say cleanly** -- colliding pairing keys,
+  duplicate force names (only the last is diffed), and rebuild pairings -- rather than returning
+  a bare hash the way the Python does. `review_findings` is **omitted** from the payload until a
+  reviewer is injected (it re-runs `review()`, which is P5): emitting an empty list there would
+  read as "no findings" when the truth is "not checked".
+- **Corrected `P1-CONTRACT.md` section 8.** It claimed `_key` can return `None` and that fields
+  with neither id nor description are "filtered out of both snapshots entirely ... invisible to
+  `delta` by construction". Verified by running the Python: `'ref:' + ''` is truthy, so the
+  `or None` branch is unreachable and `_key` never returns `None`. Those fields are not filtered
+  out -- they all collapse onto the single key `'ref:'`, so an unidentified field in `before`
+  pairs with an **unrelated** unidentified field in `after` and their differences are reported as
+  a change. Not a live defect (every membrane in the JSON export carries a validated hex `_id`),
+  but a latent trap; the port reproduces it for parity and warns on it.
+
+- **New tools `tools/template_yaml/field_walker.rb` + `tools/template_yaml/compare_fields.rb`**
+  (P3 of the template-YAML-tooling Ruby port): enumerates a template's fields in on-screen
+  LAYOUT order -- `flow_nodes` by `weight`, then `membrane_ids` / `left_membrane_ids` /
+  `right_membrane_ids`, then each id list in stored order -- porting the Python projector's
+  `walk_fields` against the contract frozen in `P1-CONTRACT.md`.
+  **Verified against the real 18-template customer dump set: 2,714 fields, ids and ordering match the
+  Python projector exactly, with 0 unexpected divergences.** The only 6 differences are the
+  `ActionsList` ids the Python's YAML path corrupts (a contiguous run of `ActionsList` ids), where
+  the Ruby is correct and the Python is not; `compare_fields.rb` whitelists those six BY VALUE,
+  so a seventh divergence -- or any ordering defect on that same template -- still fails.
+- **`FieldWalker` distinguishes "no fields" from "could not see the fields"**, which the Python
+  cannot: it returns a `Result` carrying the faithful field list plus every membrane it dropped,
+  every layout reference it could not resolve, duplicate placements, non-hash nodes and
+  defaulted weights, with `#blind?` true exactly when an empty list is untrustworthy. A
+  command-bus-built template with no layout, a `SplitSection` with no `dataFields`, and a
+  genuinely empty template all return an empty or short list from the Python with no error; they
+  are now told apart. Three port-critical quirks are preserved deliberately and covered by
+  specs: Python truthiness in the `or` chains (an empty `heading` must fall through to
+  `left_heading`, an empty `_type` must stay `''` -- `''` is truthy in Ruby), the STABLE node
+  sort (`Array#sort_by` is not stable), and `bool`-is-`int` weights.
+
+- **New tools `tools/template_yaml/loader.rb` + `tools/template_yaml/id_guard.rb`** (P2 of the
+  template-YAML-tooling Ruby port): loads an ecoPortal template backup dump from its **JSON**
+  export -- not the YAML -- and validates every id-shaped value against `/\A[0-9a-f]{24}\z/`,
+  raising loudly (template, field path, offending value) rather than letting a bad id through.
+  Reading JSON instead of YAML is deliberate: the Python projector's YAML path decodes
+  `!ruby/object:BSON::ObjectId` via a step with a silent-failure mode (confirmed unchanged on
+  the canonical post-!86 surface in `P1-CONTRACT.md`) that corrupts 6 of 2,432 fields on one
+  customer template without affecting counts. The JSON export carries identical data with plain hex
+  ids already, so the whole decode-bug class is structurally impossible on this path rather
+  than reimplemented. Verified against the real 18-template customer JSON dump set, including the 6
+  previously-corrupted `ActionsList` ids on "Yard 5S Site Standard"
+  (a contiguous run of `ActionsList` ids), which load and validate correctly.
+
+### Changed
+
+- **`ecoportal-api-v2` floor raised to `>= 3.3.5`** (was `>= 3.3.3`). 3.3.5 carries the fix for
+  `ClassHelpers#to_time`, whose rescue clause named a constant that does not exist
+  (`ArgumentArgument`), so its documented `exception: false` mode raised
+  `NameError: uninitialized constant ...ClassHelpers::ArgumentArgument` instead of returning nil.
+  This gem inherits that helper through DoubleModel, so any null or object-shaped date reaching a
+  `passdate` field hit it. ★ Side benefit: the old floor pointed at **3.3.3, which was yanked**
+  for shipping internal repository content to rubygems — a floor should not name a yanked version.
+
+### Fixed
+
+- `FieldConfig::CrossReference` could not set `enableCrossRegisterReporting` (Boolean) — the schema
+  accepts the key but no builder path could reach it. Closes the last MISSING-key advisory reported
+  by `tests/validate_commands.rb` for the `crossReference` byType key.
+
+- Stripped UTF-8 BOMs from 58 `lib/` source files (present since early development; harmless
+  to Ruby but flagged by the release smoke gate, and byte-noise for every downstream diff).
 
 ## [2.0.0] - 2026-08-13
 
@@ -10,8 +394,7 @@ Major release: everything accumulated on `main` since `v1.3.14` — the 2026-07-
 schema syncs, command-bus completion (105/105 commands), native file upload, and a long run of
 correctness fixes. **Breaking, but narrowly:** every removed or reshaped surface either targeted
 a mutation the live schema never had (so it could never have worked) or was a dead accessor with
-no consumer — a 2026-07-30 sweep of `eco-helpers`, `integration-training`, `multi_org_api` and
-`multi-org-idle` found no consumer of any breaking surface (re-confirmed 2026-08-12). The major
+no consumer — a 2026-07-30 sweep of `eco-helpers` and three internal script repos found no consumer of any breaking surface (re-confirmed 2026-08-12). The major
 bump is deliberate: consumer repos declare `~> 1.3` (which allows 1.4.x), so a minor would have
 been adopted silently on the next `bundle update`; 2.0.0 makes adoption a per-repo decision.
 
@@ -25,7 +408,7 @@ Note: this release does not descend from `v1.3.15`, which shipped from the `rele
 branch forked at 1.3.14 — do not expect a linear tag history.
 
 ★ **The published gem is now `lib/` only.** `spec.files` excluded just `test|spec|features`, so
-every top-level directory added since shipped by default — 244 files of internal `.ai-assistance/`
+every top-level directory added since shipped by default — 244 files of internal AI-tooling
 notes, `docs/` (including the rolling worklog), and `.claude/`. `spec.files` is now an allowlist
 (`lib/`, `exe/`, README, LICENSE, CHANGELOG), which also drops the package from 959 KB to 195 KB.
 All 568 `lib/` files are unchanged; nothing outside `lib/` was ever loaded at runtime.
@@ -68,7 +451,7 @@ All 568 `lib/` files are unchanged; nothing outside `lib/` was ever loaded at ru
   but only one may be published (`active: true`) per organization at a time — publishing another
   with the same uid unpublishes the incumbent. Previously the value was fetchable from the API but
   unreachable through the gem (the embed was commented out and no fragment selected it).
-  Semantics documented in `.ai-assistance/code/ecoPortal_architecture/02_data_model.md`.
+  Semantics documented in the repo's internal docs.
 - **`editTemplateContainerUid` workflow command** — `Input::WorkflowCommand::EditTemplateContainerUid`,
   registered on the command bus. Unlike its `editTemplate*` siblings it raises on a nil value rather
   than emitting an empty command (the schema argument is `String!`) and validates the backend's
@@ -96,7 +479,7 @@ All 568 `lib/` files are unchanged; nothing outside `lib/` was ever loaded at ru
   diff (adds/removes/changes/reorders, bookkeeping noise hidden by default, nil≡empty-container
   lenience for document-age drift). Detects a foreign id-space and points at
   `Diff::CrossObjectDiff` instead of emitting a misleading add/remove-everything report.
-- Scoping project `.ai-assistance/projects/data-toolset/` — coordination of the data
+- Scoping project the repo's internal docs — coordination of the data
   import/extract/migration tool-set (legacy imports, template and register metadata table
   definitions, BI warehouse extracts, spreadsheet and back-end imports, register-to-register and
   org-to-org migrations, register-revamp mapping and readiness reporting). Capability map C1-C8,
@@ -163,7 +546,7 @@ The web "System Access Logs" page and page "history changelog" are driven by
 
 - `ecoportal-api` dependency floor raised to `0.10.17`: inherits the `WithRetry` fix that
   makes `HTTP::TimeoutError` (connect/read/write timeouts) retryable — previously a single
-  transient timeout killed whole batch loops (live-confirmed on Farmers, 2026-07-30).
+  transient timeout killed whole batch loops (live-confirmed on a customer org, 2026-07-30).
 - **`graphlient` dependency now points at the published `0.9.0` release** instead of the fork's
   frozen git branch (`rellampec/graphlient@pre-v0.0.9`). `0.9.0` ships the same DSL/directive
   work the gem already relied on (`#115` `to_query_string`/`spread`, `#116` directives DSL,
@@ -286,7 +669,7 @@ The web "System Access Logs" page and page "history changelog" are driven by
   `people{id}` nodes on both sides), not the raw `peopleIds` key — the backend can return
   `peopleIds: null` on reads while still populating `people`/`cachedPeople`, so restating an
   already-attached person id no longer registers as a change. Live-confirmed 2026-07-16
-  (act-gov TOOCS dry-run reported "Updated 6/6" for a no-op). Mirrors the `CrossReference`
+  (a customer dry-run reported "Updated 6/6" for a no-op). Mirrors the `CrossReference`
   fix for the identical disease; `as_input` now serialises the fallback-aware `people_ids`
   reader instead of the raw doc key.
 - `ContractorEntities` field: the reader read the staged write key (`contractors`), which read
@@ -358,7 +741,7 @@ The web "System Access Logs" page and page "history changelog" are driven by
   **Migrate to:** `editTemplateBasicSettings` (name/icon/settings/counter/tags/folders/creator
   perms), `editTemplateDescriptions` (`description`), `editTemplateCreatorPermissions` (creator
   perms). The old `editPage` `addOtherTags`/`removeOtherTags` keys have no `editTemplate*`
-  equivalent (dropped from schema). No downstream callers existed (eco-helpers / multi_org_api /
+  equivalent (dropped from schema). No downstream callers existed (eco-helpers / internal script repos /
   gem swept) so the removal is clean. See DECISIONS.md in the workflow-space project.
 - **`Mutation::SmartFill::Generate` / `Mutation::SmartFill::SubmitFeedback` and
   `Builder::Page#generate_smart_fill` / `#submit_smart_fill_feedback`** (breaking, but dead
@@ -380,13 +763,13 @@ The web "System Access Logs" page and page "history changelog" are driven by
   to measure coverage — only the QUESTION carries one; its satellites (comment, image, document,
   recommended action) do not and are not expected to. The denominator is workbook questions
   (`question_ref`), never the field count; measuring against all fields yields a meaningless ~16%.
-- `.ai-assistance/projects/mns-template-lifecycle/WORKBOOK-FIELD-MAPPING.md` — the authoritative
+- the repo's internal docs — the authoritative
   workbook-to-template contract recovered verbatim from the 2026-08-08 session transcript:
   `QuestionSetReference` → template_container_id (UI "UNIQUE IDENTIFIER"), `QuestionReference` →
   field `description` (CONFIRMED), `QuestionInformation` → field tooltip (strip HTML entities),
   scores ignored, section-vs-stage left ambiguous, plus the template-pairing procedure and the
   DEV-site targeting note.
-- `.ai-assistance/conventions/recovering-prior-context.md` — past sessions are greppable JSONL
+- the repo's internal docs — past sessions are greppable JSONL
   transcripts on disk (35 sessions, 85 MB); search them before asking the developer something he may
   already have answered.
 
@@ -514,7 +897,7 @@ signed-off future decision.)
     (`external_id`/`id`/`state`) — a spurious path produced term `membranes.external_id.external_id`
     → 0 results (silent miss → dup-on-upsert). Register FIELD keys still get the nested path.
   - Verified against the backend filter definitions; catalogued in
-    `.ai-assistance/code/filter_contract_matrix.md`.
+    the repo's internal docs.
 
 ### Added
 
@@ -586,7 +969,7 @@ shapes checked against the live schema dump); the live UAT→PROD round trip is
   longer exists (fragments are a registry now) → `uninitialized constant … Fragment::… (NameError)` at
   render time. Now `spread :Action` / `spread :ContractorEntity`, matching the already-migrated queries.
   (The sibling breakage in eco-helpers' location-command optimizations is fixed in eco-helpers 3.2.17;
-  it crashed the live act-gov locations sync.)
+  it crashed a customer's live locations sync.)
 - **Kickstand workflow mutations — bare `DateTime` selection.** `Kickstand::{Start,Stop,Fail}Workflow`
   selected `startedAt`/`stoppedAt`/`failedAt` bare → "Field must have selections". Now
   `{ dateTime timeZone }` (same class as the 1.3.10 LocationStructure fix).
@@ -614,7 +997,7 @@ shapes checked against the live schema dump); the live UAT→PROD round trip is
 
 ## [1.3.10] - 2026-07-03
 
-Hotfix (backwards-compatible). Resolves a live failure on the Turners & Growers users sync.
+Hotfix (backwards-compatible). Resolves a live failure on a customer's users sync.
 
 ### Fixed
 

data/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2022 ecoPortal
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2022 ecoPortal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,24 +1,24 @@
-# Ecoportal::API::GraphQL
-
-This is a basic collection of helpers that can be used to interact with the
-[ecoPortal](https://www.ecoportal.com) `GraphQL` API
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'ecoportal-api-graphql', require: %w[ecoportal/api-graphql]
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install ecoportal-api-graphql
-
-## Changelog
-
-See {file:CHANGELOG.md} for a list of changes.
+# Ecoportal::API::GraphQL
+
+This is a basic collection of helpers that can be used to interact with the
+[ecoPortal](https://www.ecoportal.com) `GraphQL` API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ecoportal-api-graphql', require: %w[ecoportal/api-graphql]
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ecoportal-api-graphql
+
+## Changelog
+
+See {file:CHANGELOG.md} for a list of changes.