ecoportal-api-graphql 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e679d934d9305d1926abe7251617eea0e5333c04665672b25f5ad38afb67d9b3
-  data.tar.gz: 2b8047d56b9af371b71308bcabce23f8e4c4b67d014ce7a4095386fadb1f89f4
+  metadata.gz: 371133ecd295f75aacb3e34c85f4cc93c5561cc0b12452091fb19d73fb32adda
+  data.tar.gz: 422e949c1544c1d94dc0bd3f7f2825d5a747449976cda7eef04c51ca9da4d523
 SHA512:
-  metadata.gz: 6ec6f2792de809534943497a98a74ec012b061778d379bb9f8ac205805cd9a629386c3293ee00e647549564fed5edbbc80e73cf856340922548309b8e9c68435
-  data.tar.gz: 948f0064aa886e310fc24f78a3919cbccc3b192495c724d86d003e1ff03bd39d2d12b312e82c04ca6626779abd822f9f9914de44b651c4903ba51d275085f7e8
+  metadata.gz: 9627606e555d1fcbff9bede5d611d34fc2274c4566bae93b67e9c1821a730bbef6b8831f46061e1557f7123302c70a022af77228c2c69297a87a46bb0ee2db33
+  data.tar.gz: 291a7b865d87ec744bd23d97916808105a8cad7bad525af5862d19f7c21e367760930aa49e67af5991a181ab406cadc298b5a33ca354677fe0cc27d772ce4718

data/CHANGELOG.md

@@ -2,7 +2,369 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [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 the 18 M&S 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 the 18 M&S 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 the M&S 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/mns/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/mns/collection.rb` -- a pure-Ruby, stdlib-only read interface over the MnS 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/mns/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/mns/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-mns-18-templates.md`.
+
+- **`tools/mns/cli.rb`** -- a Ruby CLI that creates/lists/destroys the M&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 the M&S 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/mns/webhooks.rb` (`MnsWebhooks::Documents`) as pure
+  functions, spec'd in `spec/tools/mns/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 `.ai-assistance/code/template_change_log.md`.
+
+- **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 M&S 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 (`6a4c4f12316577006e210b7a`..`..b7f`), 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
+  M&S 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 M&S JSON dump set, including the 6
+  previously-corrupted `ActionsList` ids on "Yard 5S Site Standard"
+  (`6a4c4f12316577006e210b7a`..`..b7f`), 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
 

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.