ecoportal-api-graphql 2.2.0 → 3.0.0

data/CHANGELOG.md

@@ -2,6 +2,424 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
@@ -51,7 +469,7 @@ caller adapting to this is changing working-looking code.
   `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.
+  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
@@ -73,7 +491,7 @@ caller adapting to this is changing working-looking code.
   -> `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`**,
+  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,
@@ -116,9 +534,9 @@ caller adapting to this is changing working-looking code.
 - **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
+  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/mns/cli.rb`
+  (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.
 
@@ -212,30 +630,30 @@ closes.
   `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
+- `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/mns/collection_sync_spec.rb` pins the webhook-admin and build/update-page
+  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/mns/README.md`.
+  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-mns-18-templates.md`.
+  `tools/template_yaml/reviews/2026-08-09-<customer>-18-templates.md`.
 
-- **`tools/mns/cli.rb`** -- a Ruby CLI that creates/lists/destroys the M&S webhook
+- **`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 the M&S UAT org, EU
+  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/mns/webhooks.rb` (`MnsWebhooks::Documents`) as pure
-  functions, spec'd in `spec/tools/mns/webhooks_spec.rb` with no network involved.
+  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
@@ -286,7 +704,7 @@ closes.
   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`.
+  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
@@ -318,9 +736,9 @@ closes.
   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
+  **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 (`6a4c4f12316577006e210b7a`..`..b7f`), where
+  `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
@@ -341,11 +759,11 @@ closes.
   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
+  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 M&S JSON dump set, including the 6
+  than reimplemented. Verified against the real 18-template customer JSON dump set, including the 6
   previously-corrupted `ActionsList` ids on "Yard 5S Site Standard"
-  (`6a4c4f12316577006e210b7a`..`..b7f`), which load and validate correctly.
+  (a contiguous run of `ActionsList` ids), which load and validate correctly.
 
 ### Changed
 
@@ -372,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.
 
@@ -387,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.
@@ -430,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
@@ -458,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,
@@ -525,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,
@@ -648,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
@@ -720,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
@@ -742,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.
 
@@ -876,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
 
@@ -948,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).
@@ -976,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