ecoportal-api-graphql 2.0.0 → 3.0.0

data/CHANGELOG.md

@@ -2,7 +2,787 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [3.0.0] - 2026-09-29
+
+**Major, not minor:** `Base::Page::DataField::ImageGallery#file_container_ids`/
+`#file_container_ids=` are REMOVED (see the first entry under `Changed`, below) -- a real
+public-interface removal, not merely an addition, so this is a major version bump under
+the versioning convention (minor = additive/breaking-but-additive, major = removal).
+`lib/ecoportal/api/graphql/forces/` also left this gem for `oscar/eco-forces` (see the
+`Changed` entry below) -- NOT breaking for any rubygems.org consumer (never packaged in a
+released version). `lib/ecoportal/api/graphql/dsl/` left earlier, for `oscar/eco-dsl-dialects`
+(FAAP-106 L2, `0bb6cd2`) -- also never released, and (owner ruling) not itself re-announced
+here since there is nothing to announce; only this gem's own release guard and the fragments
+whose described code STAYED are recorded below. **`lib/ecoportal/api/graphql/versioning/`
+is likewise never packaged** (owner ARCHITECTURE ruling, PERKS, same day) -- unlike `dsl/`/
+`forces/`, the CODE stays in this repo for now (extraction to its own private gem is a
+follow-up card); every `Versioning::*`/`TemplateRegistry`/`DiffProfile`/`ProfileRunner`
+entry this release would otherwise have listed is dropped from this changelog entirely
+(none of it has ever shipped in a released version either) -- see the one `Removed` line
+below.
+
+### 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.
+
+- Test/tooling: DSL-08 emitter equivalence acceptance test
+  (`spec/ecoportal/api/graphql/emitters_equivalence_spec.rb`) and a new pure
+  `Model::Template::CommandNormalizer` helper (`lib/.../model/template/command_normalizer.rb`)
+  that repositions placeholder/id tokens to position and deep-sorts command keys so batches
+  from different emitters can be compared for structural equivalence. Measures (does not yet
+  fix) 8 real divergences between `Builder::TemplateBuilder`, `Diff::CommandSynthesizer`,
+  `Model::Template::CommandSynthesis`, the `template_field_config` DSL dialect, and the
+  a downstream script repo's writers against a shared one-stage/one-section/one-Select-field/
+  one-force/one-binding fixture -- see `TEMPLATE-MODEL-DESIGN.md` section 8 for the full
+  divergence table and fix plan. No production behaviour changed by this fragment.
+
+- **`FileUpload::Client#upload_image`/`#upload_all_images`** — uploads a local file into the
+  Image Gallery upload pipeline (`uploadImage` → a `TempImage`, NOT `uploadFile` →
+  `FileContainer`) and returns the `TempImage` id (the `sourceId` an `ImageInput` write
+  needs). Shares its presign + S3-POST step with `#upload`/`#upload_all` (same collision-proof
+  key convention, same field order) — only the registration mutation differs. Same
+  `Error` hierarchy, same `:signature`/`:storage`/`:register` hooks, same bounded-concurrency
+  batch semantics as the existing File-container upload. New: `Mutation::Image::Upload`
+  (wraps `uploadImage(input: ImagesUploadInput!)`), `Payload::ImagesUpload`,
+  `Base::TempImage`/`Model::TempImage` (`id`, `s3Key`, `error`, `complete`).
+- **`Base::Page::DataField::ImageGallery#add_source_images`** — merge-safe writer for Image
+  Gallery fields (mirrors `FileField#file_container_ids=`'s kept-vs-new split): keeps every
+  currently-loaded image (echoed back as `{id:}` — `ImageGalleryInput.images` is a FULL
+  REPLACE server-side, same trap as `FileField#items`) and adds new ones (`{sourceId:,
+  weight:, fileName:}`, `sourceId` being a `TempImage` id from `#upload_image`), at
+  sequential weights starting at `#next_weight` (one past the current maximum — there is no
+  server-side auto-increment for `weight`). Also adds `#images`/`#image_ids`/`#next_weight`
+  readers.
+
+- `Model::Template.load(api, id:)` / `Model::Template::Instance` — the mutable, "three
+  lines" editable template model (the repo's internal docs): `template = Model::Template.load(api, id:); template.fields.each
+  { |f| f.label = ... }; template.save!(api)`. Reconciles the gem's existing one-shot
+  `Builder::TemplateBuilder`/`Diff::CommandSynthesizer` command-emission layer with the
+  a downstream script repo's toolkit's proven staged/chunked write pattern
+  (`CommandBatchExecutor`, `TemplateFieldsRead`, `SectionWriter`/`FieldWriter`/
+  `SelectOptionWriter`/`ForceAndBindingWriter`), promoted here as a GENERIC gem primitive
+  rather than duplicated per org.
+  - `#as_commands` — diffs the in-memory tree against its load-time snapshot, ordered stage
+    -> section -> field -> option/config -> force -> helper -> binding, with a per-stage
+    `reorderSection` trailer.
+  - `#save!(api, simulate: true)` (default) returns the staged PLAN with no server call;
+    `simulate: false` executes it through `Builder::Template#update` (`updatePageTemplate` —
+    never `executeWorkflowCommands`, per `18_template_editor_save_path.md` section D.4's own
+    recommendation), chunked (`Model::Template::CommandGrouper`, a generic union-find grouping
+    that never splits a placeholder-minting command from a same-batch dependent), staged in
+    four phases (stage / section / field+option / force / helper+binding) with a live re-read
+    + positional/count-guard/cross-check id resolution between phases — any number of
+    stages/sections/fields/forces, not one template's shape.
+  - `#verify(api)` re-reads and reports per changed property `verified`/`mismatch`/`missing`
+    against the model's OWN current (post-save) state.
+  - `Builder::Template#update` / `Mutation::Template::Update#query` gained an optional
+    `client_mutation_id:` (omitted when not given — the pre-existing call shape is byte-
+    identical for every other caller) for `StagedExecutor`'s own per-chunk tracing id.
+
+- `rewrite_field_labels`/`rewrite_field_tooltips` results now carry a `selection_digest`
+  (a sha256 hex digest over the sorted touched field ids + their before-values -- never the
+  values themselves) -- `verify_field_labels`/`verify_field_tooltips` gained an OPTIONAL
+  `expected_selection_digest` argument: when given and it differs from a fresh digest of
+  the current selection, the verify call refuses with `selection_drift: true, verified:
+  false` and both digests (hex only) instead of the usual buckets. Closes "apply requires
+  a paired verify over the SAME selection" pinning a PREDICATE, not a fixed set -- the live
+  field set (or a field's own value) can change between a rewrite call and a later verify
+  call (a field added, a label hand-edited, a force re-installed) with nothing to detect
+  it (eco-forces consumer review finding F-04). Fully backwards compatible: omitting
+  `expected_selection_digest` verifies against the current selection exactly as before.
+  See the repo's internal docs, "Selection digest".
+
+### Changed
+
+- **BREAKING:** `Base::Page::DataField::ImageGallery#file_container_ids`/
+  `#file_container_ids=` are REMOVED — an Image Gallery image was never a `FileContainer`;
+  `ImageGalleryInput` has no `fileContainerIds` on the live schema (confirmed against the live
+  ecoPortal server source — `ImageGalleryInput` takes `images: [ImageInput]`, referencing a
+  NEW image by `sourceId`, a `TempImage` id from the separate `uploadImage` mutation, never a
+  `fileContainerId`). The old accessors read/wrote a doc key (`fileContainers`) the live API
+  never returns or accepts — any caller depending on them was already silently broken (see the
+  three characterization bugs closed below). Replaced by `#images`/`#image_ids`/
+  `#add_source_images` (see `Added`, above) — a caller previously doing
+  `field.file_container_ids = [...]` should now upload via
+  `FileUpload::Client#upload_image` and call `field.add_source_images([{source_id:,
+  file_name:}, ...])` instead.
+
+- `imageGalleryField` (`Fragment::Pages::CommonPageUnion`) now selects `id`/`weight` on each
+  `images` item — both were previously omitted entirely, which is why no correct reader was
+  possible before this fix (see the `Fixed` entry below).
+- `fileName`/`fileSize` on an Image Gallery image are confirmed NULLABLE server-side even on
+  a successful upload (a documented upstream platform bug, per the live schema's own field
+  comment) — any comparison built on either must treat a nil on either side as "not a
+  confident match", never a positive one. Documented on
+  `Base::Page::DataField::ImageGallery`'s own header.
+
+- **Changed (behaviour):** `Base::Page::DataField::ImageGallery#as_input` now echoes a KEPT
+  (currently-existing, untouched) image with its FULL `ImageInput` field set — `id`,
+  `sourceId` (read back from `uploadId`), `weight`, `caption`, `fileName`,
+  `sensitiveContent`, `inaccurateDescription`, `inaccurateExtractedText` — instead of a bare
+  `{id:}`. `ImageGalleryInput.images` is a full replace server-side
+  (`assign_attributes_service.rb#set_image_gallery_attrs` → `format_removed_ids`): a bare
+  `{id:}` is read by the server as "clear every other attribute on this image", not "leave
+  it as it is" — the previous shape silently reset caption/moderation flags to their
+  defaults on every write that merely appended a new photo alongside existing ones.
+  `#add_source_images` now keeps each existing image's FULL doc entry (not collapsed to a
+  bare `{id:}`) so this echo has the data to build from. `#add_source_images`'s own
+  kept-vs-new merge semantics (weight = current max + 1, sequential) are unchanged.
+
+- `lib/ecoportal/api/graphql/forces/` (dry-run docking, the L1 force-representation
+  reader/bridge/history slice, the conformance harness -- 14 files) is REMOVED from
+  this gem and moves to `oscar/eco-forces` (owner ruling R-2026-09-28-64 D-19:
+  eco-forces is the most sensitive IP in this stack, so the GraphQL client adapter
+  code that docks directly into it gets its own repo, same reasoning as the earlier
+  `dsl/` -> `eco-dsl-dialects` move). NOT BREAKING for rubygems.org consumers: this
+  tree was never published in any released version of this gem -- confirmed 0 files
+  under this path in every release through 2.2.0 (measured via `gem fetch` +
+  `Gem::Package#contents`, per the release-guard's own header). The only consumer this
+  could ever have reached is a repo-checkout-level `require
+  "ecoportal/api/graphql/forces"` (opt-in, never part of the main require chain, only
+  resolvable under the now-removed `Gemfile.forces`). `lib/ecoportal/api/graphql/
+  forces/CLAUDE.md` stays as a short pointer (same pattern as `dsl/CLAUDE.md`). The
+  release guard (`scripts/audit/dsl_release_guard.rb`) keeps its own
+  `lib/ecoportal/api/graphql/forces/` protected-prefix entry, now lifted by this MR's
+  own `docs/audits/rulings/forces-licence-ruling.md` -- independent of `dsl/`'s own
+  entry, which stays blocked until a separate ruling exists.
+- `Gemfile.forces` removed entirely -- nothing else in this gem required eco-forces
+  (confirmed: a full-repo grep for `eco/forces`/`eco-forces`/`Eco::Forces` outside the
+  removed tree found only doc/tooling mentions unrelated to any require path). Its
+  `.rubocop.yml` exclude entry removed with it.
+- `tools/forces-conformance/` and `tools/forces-l1/` removed -- both existed only to
+  drive the now-removed lib tree (their own `require_relative`s pointed directly into
+  it); both moved to `oscar/eco-forces` verbatim instead (same commit/MR as the tree
+  itself).
+- The six `changelog.d/` fragments describing this tree's own prior history
+  (`added-forces-conformance-harness.md`, `added-forces-docking-dry-run.md`,
+  `added-forces-l1-dump-adapter.md`, `added-forces-l1-history.md`,
+  `added-forces-l1-reader-bridge.md`, `fixed-forces-parity-rerun-protocol-run.md`) are
+  DELETED from this gem's changelog.d and migrated, reworded only where a path/name
+  changed, into `oscar/eco-forces`'s own `CHANGELOG.md` `[Unreleased]` section -- this
+  gem never shipped a tagged release carrying any of them, so nothing is lost from
+  this gem's own history by moving them. `security-faap-906b-guard-forces.md` (the
+  guard itself, not the moved code) stays here, unchanged.
+
+**Migration:** if you were requiring `ecoportal/api/graphql/forces` at the
+repo-checkout level (never possible via the published gem, see above), add
+`eco-forces` to your own Gemfile instead -- see that gem's README, "GraphQL client
+adapters (moved from ecoportal-api-graphql 3.0.0)".
+
+- **Changed (behaviour):** `Input::Page::Update.from_model` now defaults `client_mutation_id:`
+  to a fresh `SecureRandom.uuid` per call instead of an omitted empty string — every
+  `updatePage` mutation this input builds is now traceable by default (correlation only; the
+  server does NOT dedupe mutations on `clientMutationId`, so this buys no idempotency — a
+  retried call with the same id still re-applies the write). Pass an explicit
+  `client_mutation_id:` to correlate several calls under one value, or `''`/`nil` to omit the
+  key entirely (unchanged).
+
+- **Changed** `scripts/release_smoke_check.rb` (release tooling, not packaged in the gem): the
+  packaging gate now honours per-gem exceptions declared in a `.release-smoke-allow` file at the
+  gem root — one EXACT packaged path per line, no globs — plus a `RELEASE_SMOKE_EXTRA_ALLOWED`
+  env override for one-off runs. Needed because the shared gate hardcoded `lib/**/*.rb` and
+  refused eco-helpers 3.3.2, whose three JSON data files are loaded at require time and are
+  allowlisted by its own gemspec and packaging spec. Exceptions are themselves gated: a declared
+  path missing from the package FAILS (stale declarations cannot rot silently), and a declared
+  `.json` file must parse. Proven red-then-green against the real eco-helpers-3.3.2.gem artifact.
+
+### 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.
+
+- `AuthService::InstanceMethods#session_token_renewed` read the wrong hash key when no
+  explicit `refresh_token:` was given -- `body['resfresh_token']` (typo) instead of
+  `body['refresh_token']` -- so a session refresh attempted without an explicit token
+  always silently returned `nil` instead of renewing, even though the server's own
+  response body carried a real `refresh_token`. Fixed at
+  `lib/ecoportal/api/common/graphql/auth_service.rb`.
+  Zero specs existed for `AuthService` before this fix; `spec/ecoportal/api/common/
+  graphql/auth_service_spec.rb` now covers `#session_token` (happy path, the
+  auto-renew window, `auto_renew: false`, and a failing `session_token_data` call),
+  `#session_token_renewed` (explicit `refresh_token:`, reading it from the body, a
+  missing key, and a failing refresh call), and `#token_renew?`'s own boundary
+  (`TOKEN_AUTORENEW * 60` seconds, exactly at / one second inside / one second
+  outside) -- with a plain-Ruby fake HTTP client, no network, no new gem dependency.
+
+- `Model::Template::CommandSynthesis` now emits `stageId` on `editFieldConfiguration` when
+  the owning template is phased (a new `Instance#phased?`, derived from the read's own
+  `page['__typename']`) -- `Field` always carries a `#stage` reference, but the command never
+  threaded it through, so editing a field via `Model::Template#save!` on a phased page would
+  omit a schema-required disambiguator and 500 server-side (found measuring DSL-08's emitter
+  equivalence acceptance test against the DSL dialect's own tested binding and the downstream
+  `FieldWriter`, both of which already got this right). `stageId` is still correctly OMITTED
+  (never sent as an explicit `null`) when the template is non-phased.
+
+- `Ecoportal::API::Common::GraphQL::HttpClient#base_request` (the only place in this gem's
+  dependency chain that talks to the server via `http.rb`; every live GraphQL query goes
+  through it via `Logic::BaseQuery#graphql_query` -> `client.http_client.execute`, and the
+  OAuth token POST in `AuthService#auth_http_client` reuses the same method) called
+  `.timeout(read: READ_TIMEOUT, write: WRITE_TIMEOUT)` without a `connect:` value. http.rb's
+  `HTTP::Timeout::PerOperation` (`lib/http/timeout/per_operation.rb`) defaults any timeout key
+  NOT given to 0.25 seconds, so `@connect_timeout` stayed at that 0.25s library default even
+  though read/write were correctly set to 90s. `connect_ssl` (the TLS handshake) uses
+  `@connect_timeout` via `rescue_readable`/`rescue_writable`, whose error text is
+  unconditionally "Read timed out after #{@read_timeout} seconds" -- so a slow TLS handshake
+  against the EU instance surfaced as `HTTP::TimeoutError: Read timed out after 0.25 seconds`
+  even though the actual `@read_timeout` was 90 the whole time. Live-confirmed 2026-09-08 via
+  backtrace: `connect_ssl` -> `start_tls` (`http/connection.rb`) -> `Common::Client#post` ->
+  `AuthService#session_token_data` -> `Common::GraphQL::Client#initialize`. Added a
+  `CONNECT_TIMEOUT = 30` constant alongside `READ_TIMEOUT`/`WRITE_TIMEOUT` and pass
+  `connect: CONNECT_TIMEOUT` in the same `.timeout(...)` call. Read and write were never the
+  problem and are unchanged.
+
+- `Ecoportal::API::Common::GraphQL::HttpClient#base_request` (the only place in this gem's
+  dependency chain that talks to the server via `http.rb`; every live GraphQL query goes
+  through it via `Logic::BaseQuery#graphql_query` -> `client.http_client.execute`, and the
+  OAuth token POST in `AuthService#auth_http_client` reuses the same method) built a plain,
+  non-persistent `HTTP` client. http.rb sends `Connection: close` on every request from a
+  non-persistent client (`http/client.rb`: `default_options.persistent? ? KEEP_ALIVE : CLOSE`).
+  Live-confirmed 2026-09-08: `eu.live.ecoportal.com` closes any HTTP/1.1 request carrying that
+  header without ever sending a response -- immediately, or after ~61s -- which surfaced in
+  Ruby as `OpenSSL::SSL::SSLError: SSL_read: unexpected eof while reading`. The same Ruby stack
+  with a persistent (keep-alive) client works (`HTTP.persistent("https://eu.live.ecoportal.com")
+  .post(...)` -> 200 in 1.9s); Sydney (`live.ecoportal.com`) is fine either way. `base_request`
+  now returns a client made persistent to the configured host (`HTTP.persistent(base_url,
+  timeout: KEEP_ALIVE_TIMEOUT)`, new `KEEP_ALIVE_TIMEOUT = 5` constant) before chaining the
+  existing `.accept(:json).timeout(...)`. Confirmed against the installed http.rb 5.3.1 source
+  that this is safe: one `HttpClient` is bound to one host, so `HTTP::StateError` (raised only
+  on a cross-origin request against a persistent client, `client.rb#verify_connection!`) cannot
+  occur here; and an expired or dead persistent connection is transparently closed and
+  reconnected on the next request (`verify_connection!` checks `@connection.expired?` /
+  `keep_alive?` and calls `close`, then `perform` lazily re-opens via
+  `@connection ||= HTTP::Connection.new(...)`), with any resulting `HTTP::ConnectionError`
+  already covered by the inherited `Common::Client` retry pipeline. `execute` and the rest of
+  the retry/throttle pipeline are unchanged.
+
+- **Fixed:** `imageGalleryField` (`Fragment::Pages::CommonPageUnion`) now also selects
+  `sensitiveContent`, `inaccurateDescription`, `inaccurateExtractedText` on each `images`
+  item, alongside the pre-existing `id`/`weight`/`downloadUrl`/`caption`/`fileName`/
+  `fileSize`/`uploadId` — every `ImageInput`-echoable attribute is now read in one query, so
+  `#kept_image_input`'s full-field echo (see the `Changed` entry above) never needs a
+  follow-up read. `fileName`/`fileSize` remain documented NULLABLE even on a successful
+  upload (upstream platform bug) — never treat a nil on either as a confident match.
+
+- `Base::Page::DataField::ImageGallery`'s reader closes all three defects
+  `image_gallery_characterization_spec.rb` documented: BUG-3a (reader keyed on the wrong doc
+  key, `fileContainers` instead of `images` — see `Changed`, above, for the fragment fix this
+  needed first), BUG-3b (the fragment omitted `images[].id`, so no correct reader was
+  possible), and BUG-3c (a pure read injected a phantom `fileContainers` key into `doc`) — the
+  new reader is a plain `doc['images']` accessor (no `passarray`), so a pure read no longer
+  mutates `doc` at all, a stronger fix than the prior array-diff no-op (MR !106) gave the old
+  reader.
+
+- `Common::GraphQL::Client#schema` no longer lets graphql-ruby's "Input Object types must
+  have arguments" warning leak out for the argument-less INPUT_OBJECT types the live
+  ecoPortal schema actually ships (confirmed today: `SupervisedPeopleFieldValuesGeneratorInput`,
+  `DiscreteMetadataFilterWidgetInput`, `DateFilterWidgetInput`, `PeopleFilterWidgetInput`,
+  `ByUserAnalysisInput`, `ByTypeAnalysisInput`, `ByRelativeStatusAnalysisInput`,
+  `TemplatesAnalysisInput`, `RestorePageOperationInput`, `UnarchiveOperationInput`,
+  `ArchiveOperationInput`, `DeleteFilesOperationInput` -- 12 types, 0 after the fix).
+  `GraphQL::Schema::Loader` (used by `GraphQL::Schema.from_introspection`, which
+  `Graphlient::Schema` / `GraphQL::Client.load_schema` call to build our client-side schema
+  from the server's raw introspection JSON) defines one `GraphQL::Schema::InputObject`
+  subclass per INPUT_OBJECT type but never calls `has_no_arguments(true)` on the ones whose
+  `inputFields` came back empty -- so graphql-ruby warns (and, in a future version, will
+  raise) the first time anything asks such a type for its arguments, which happens whenever
+  the loaded schema is re-serialized (`schema.to_json` / `to_definition`), as eco-helpers'
+  `-graphql-schema` use case does. The live server never warns because its own Ruby classes
+  are defined with real argument lists (or `has_no_arguments(true)` already set) -- only the
+  client-side schema rebuilt purely from introspection data loses that annotation, so the fix
+  belongs here rather than in graphlient/graphql-client/graphql-ruby or in eco-helpers.
+  `#schema` now walks the freshly loaded schema's types once and calls the library's own
+  `has_no_arguments(true)` on every INPUT_OBJECT with no arguments, leaving types that do have
+  arguments untouched. No pre-processing of the introspection JSON, no schema shape change.
+
+- **Fixed:** `updatePage` on a PHASED page has been observed to 500 when `input.stageId` is
+  missing on an Image Gallery / File field write (live-diagnosed, page
+  a customer's phased page) — `Input::Page::Update.from_model` now DERIVES a default
+  `stageId` from the owning stage of the data fields being changed in the same call (walks
+  `model.stages`/`Stage#stage_field_ids`), for both `dataFields.updates`/`.additions` and
+  `.deletions`. A `BasicPage` (no `#stages` at all) is unaffected — `stageId` is omitted
+  entirely, never sent as an explicit `null`. Explicit `stage_id:` still overrides the
+  derivation. If the fields being updated in ONE call span more than one stage,
+  `from_model` now raises a clear `ArgumentError` instead of guessing which stage's id to
+  send — split such a change into one call per stage, in stage order, re-fetching the page
+  (fresh `patchVer`) between calls. Corrects a stale doc comment on `#require_stage!` that
+  claimed "a plain field update ... needs no stage" — true only for a `BasicPage`.
+
+- `Ecoportal::API::GraphQL::DSL::TemplateFieldConfig::Generator.declare_rewrite!`'s
+  `rewrite_field_<x>s`/`verify_field_<x>s` set-shaped verb pair now declares `acts_on` as
+  the UNION of every element noun type it can reach (`template` AND `data_field` -- was
+  `template` only). A set-shaped verb reaches EVERY `DataField` matching its pattern, not
+  just the template it is invoked against; under-declaring `acts_on` would under-approximate
+  a future eco-dsl-core strict-mode required-class set (found by the eco-forces consumer
+  review of this convention, finding F-07 -- `eco-dsl-core` `docs/reviews/2026-09-22-set-
+  shaped-verb-forces-consumer-review.md`).
+
+- `spec/ecoportal/api/graphql/diff/{version_diff_spec,command_synthesizer_spec,deploy_spec,
+  version_diff_typed_config_spec,version_diff_modalities_spec}.rb` each duplicated the same
+  `fixture(name)` helper calling `File.read(path)` with no `encoding:` -- under a non-UTF-8
+  ambient locale (`LANG=C LC_ALL=C`, no `RUBYOPT` encoding flags) this raised
+  `Encoding::InvalidByteSequenceError` inside `JSON.parse` on the first non-ASCII byte in a
+  fixture, before a single document was even parsed (35 spec failures reproduced this way).
+  JSON is always UTF-8 per its own spec (RFC 8259 SS8.1), never a guess. Extracted the
+  duplicated helper into a single shared `Support.template_fixture` (`spec/support/
+  template_fixtures.rb`, `encoding: 'UTF-8'`); the five spec files now delegate to it. Spec
+  code only -- no `lib/` change. Verified: `LANG=C LC_ALL=C bundle exec rspec` and the normal
+  `bundle exec rspec` both green (2069 examples, 0 failures, 45 pending either way).
+
+- `Mutation::Template::Create` / `Builder::Template#create` now accept an optional
+  `register_id:`, sent as `CreatePageTemplateInput.registerId` (verified against the live SDL,
+  2026-09-04 — `registerId: ID` is an INPUT FIELD, because
+  `Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation` folds the backend's
+  `argument :register_id` into the generated input object). Without it a template create is
+  **unauthorizable**, not merely unbound: the backend resolves a page's registers by tag
+  (`NewEp::Pages::AssociatedRegisters` — org registers whose `filter_tags` are a subset of the
+  page's `combined_tags`) and `RegisterTemplatePermissionChecker` returns `false` outright when
+  that set is empty. A template created with no `registerId` carries no `base_tags`, so it
+  matches zero registers, so the check fails no matter what the account is granted — surfacing
+  as the misleading `You are not authorized to perform: edit_template_basic_settings`.
+  `Pages::Templates::CreateForm#bind_register!` is what closes the hole, setting
+  `page.base_tags = register.filter_tags` before the command batch runs.
+  A nil `register_id:` is OMITTED, never sent as an explicit null, so every existing call site
+  produces the byte-identical input it produced before.
+
+- `tools/template_yaml/cli.rb --delta` now wires `reviewer: Review.method(:call)` into
+  `Delta.call`, so the printed JSON always carries a `review_findings` key (`{'before' => [...],
+  'after' => [...]}` of Review finding triples), matching the fixture ground truth the
+  ep-rovo-qa delta-verification agent reads. It also merges a top-level **`warnings`** key
+  (`Delta::Result#warnings`) into the printed JSON -- pairing-key collisions, duplicate force
+  names, rebuilt-field counts -- so the `colliding_keys` false-pairing trap reaches the consumer
+  instead of being silently dropped. `Delta::Result#payload` itself is unchanged (it stays
+  byte-for-byte comparable to the Python projector's JSON); `warnings` is added by the CLI only,
+  on top of the payload, for `--delta` output specifically.
+- Documented, in `cli.rb`'s header and `id_guard.rb`'s header, that `IdGuard`'s `HEX24` check is
+  a plain regex (`/\A[0-9a-f]{24}\z/`) with no ObjectId timestamp/counter decoding and no
+  uniqueness check beyond it -- confirming `md5(readable-name)[:24]` as an accepted convention for
+  synthetic fixture ids (a hex-24 string of either provenance passes identically).
+
+### Removed
+
+- `versioning/` (git-core diff/versioning) is a perk -- not packaged in the public gem;
+  available from a private gem in a follow-up.
+
+### Security
+
+- **Security (release gate):** `scripts/release_smoke_check.rb` now also gates packaged CONTENT,
+  not only which files ship. Every packaged text file is scanned for object ids, the private
+  source-host name, internal documentation paths, internal repository names, and a local
+  (never-shipped) denylist of customer names; hits fail the release unless excused by an exact
+  line in `.release-content-allow`. The gem now ships a short public `README.gem.md` instead of
+  the repository's developer README, and code comments and this changelog were reworded to
+  remove internal identifiers.
+
+- New `bundler-audit` CI job (MIDW-909): runs `bundle exec bundle-audit check
+  --update` on every merge-request and branch pipeline, `allow_failure: false`.
+  `bundler-audit` (`~> 0.9`) added to the `Gemfile` (repo-local CI tool, not a
+  gemspec dependency).
+- Fixed the "Insecure Source URI" finding the job first reported: the optional
+  `anthropic` dependency (only needed for `SearchConf::AIGenerator` live tests)
+  no longer has its own `source 'http://rubygems.org' do ... end` block -- it is
+  folded into the file's top-level `https://rubygems.org` source (owner ruling
+  2026-09-29, option a). The block existed to bypass local SSL inspection on
+  some developer machines (e.g. Norton Antivirus); that workaround now belongs
+  on the machine (point `SSL_CERT_FILE` at the OS certificate store's CA
+  bundle), not in the dependency source URI. `bundle exec bundle-audit check
+  --update` now reports no vulnerabilities.
+
+- Added a release guard, `scripts/audit/dsl_release_guard.rb`: no gem build that
+  packages a path under `lib/ecoportal/api/graphql/dsl/` may be published (CI job
+  `dsl-release-guard` on every pipeline; `rake release:build`, before the smoke check)
+  until `docs/audits/rulings/dsl-licence-ruling.md` carries a `RULED:` line. Stopgap
+  while the DSL licence question (FAAP-906) is open; does not change `LICENSE`, the
+  gemspec licence field, or `spec.files`.
+
+- Extended the release guard, `scripts/audit/dsl_release_guard.rb` (FAAP-906): the
+  protected prefixes are now a list, each lifted independently by its own ruling
+  file. No gem build that packages a path under `lib/ecoportal/api/graphql/dsl/` OR
+  `lib/ecoportal/api/graphql/forces/` may be published (CI job `dsl-release-guard`;
+  `rake release:build`) until THAT prefix's own ruling file
+  (`docs/audits/rulings/dsl-licence-ruling.md` or
+  `docs/audits/rulings/forces-licence-ruling.md`) carries a `RULED:` line --
+  R-2026-09-28-64 (D-19): eco-forces is the most sensitive IP. Measured: the
+  published 2.2.0 gem ships zero files under either prefix. Does not change
+  `LICENSE`, the gemspec licence field, or `spec.files`.
+
+- Extended the release guard, `scripts/audit/dsl_release_guard.rb`, with a THIRD
+  protected prefix, `lib/ecoportal/api/graphql/versioning/` (owner ARCHITECTURE
+  ruling 2026-09-29: dsl dialects, forces, and git-core diff/versioning are perks,
+  not core). No gem build that packages a path under this prefix may be published
+  until `docs/audits/rulings/versioning-licence-ruling.md` carries a `RULED:` line.
+  Unlike the dsl/forces rulings, this ruling file records that the prefix stays
+  blocked by design -- extraction to a private gem is a follow-up card, not
+  something this ruling completes. Measured: 0 packaged paths under all three
+  prefixes. Does not change `LICENSE`, the gemspec licence field, or `spec.files`.
+
+## [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 +790,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 +804,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 +847,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 +875,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 +942,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 +1065,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 +1137,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 +1159,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 +1293,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 +1365,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 +1393,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