ecoportal-api-graphql 2.2.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 128e83d1aa8d0fa5b9e4ce95f8bbd5f8bd4f219ea7d7a94dd18ec31225ac3ce9
-  data.tar.gz: 7d79138b320e6ba09221bd79a4c341ef9dc039f4ccf6923567f3f4b36f657c27
+  metadata.gz: 90830a81a4ad762cf9a4a74e08d3898076e15f09ce677e78e7f0d5809c5517fb
+  data.tar.gz: 04c5d2c47000df72cbb2a3a705622ccc6c2a80340bae6745dc088b5bf5151d73
 SHA512:
-  metadata.gz: 04cb9487e78e2f11b4c71572bc17915570a8638da67df94cfa27f0dfb3400d2c9f67bcaf25ac1b5bb61f86f1884f5af88b3adf961528ef8d3e5567607fcc1140
-  data.tar.gz: 3036e3e2295a5a2eb5876e66b145d09f3fd1a96fc174234f77621b0cd553ad2e501dc4d9c1baf74077990d9ed03c77e9bb8c8858cec97005e7dbefbeb05bda45
+  metadata.gz: fee4494637c2fc0d591a0dccbbbb740cb3f99809be5205bf25be36f9d6d42ee3a956a06d2700f5baba2cb9bb8682abf4f7b31d792f84e84992b2c485ba605b1d
+  data.tar.gz: df0b9542b045c52224135f8dcaa50f9579ddcf9363e3ea7e774e1330a5b69227aac8134e66a1752586b7f4bba94ff63d46c7f7eefeec36df25bcba041d8a5c98

data/CHANGELOG.md

@@ -2,13 +2,191 @@
 
 All notable changes to this project will be documented in this file.
 
-## [2.2.1] - 2026-09-30
+## [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.
 
-### Security
+### 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
 
-- Security republish of `2.2.0` -- backwards-compatible: removes customer and internal identifiers
-  from shipped comments and this changelog. Packaging is unchanged: `2.2.0` already shipped only
-  allowlisted files (`lib/**/*.rb` plus the named root docs).
+- **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
 
@@ -18,11 +196,229 @@ All notable changes to this project will be documented in this file.
   longer selects them. The model accessors are kept, deprecated, and now always return `nil`, so
   callers do not break. Affects every earlier version, including 2.2.0.
 
-### Added
+- `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).
 
-- **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.
+### 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
 

data/README.gem.md

@@ -0,0 +1,53 @@
+# ecoportal-api-graphql
+
+A Ruby client for the ecoPortal GraphQL API: typed models for pages, templates, data fields and
+registers, query and mutation helpers, and the workflow command bus for granular template edits.
+
+This is the README shipped inside the published gem. The source repository keeps its own
+developer README.
+
+## Install
+
+```ruby
+gem 'ecoportal-api-graphql', require: %w[ecoportal/api-graphql]
+```
+
+```
+$ bundle
+# or: $ gem install ecoportal-api-graphql
+```
+
+## Requirements
+
+| | version |
+|---|---|
+| Ruby | `>= 3.2.2` |
+| `ecoportal-api` | `~> 0.10, >= 0.10.17` |
+| `ecoportal-api-v2` | `~> 3.3, >= 3.3.5` |
+| `graphlient` | `>= 0.9.0, < 0.10` |
+
+## Example: load and edit a template
+
+```ruby
+api      = Ecoportal::API::GraphQL.new(email: ..., pass: ..., org_id: ...)
+template = Ecoportal::API::GraphQL::Model::Template.load(api, id: template_page_id)
+template.fields.each { |f| f.label = "#{f.label} (reviewed)" }
+template.save!(api, simulate: false)   # simulate: true is the default -- inspect first
+```
+
+`save!` simulates by default: it reports the commands it would send without writing anything.
+Pass `simulate: false` to apply them.
+
+## Optional extensions
+
+Some capabilities are distributed separately as optional extensions and are not part of this
+gem. The gem works fully without them; when an extension is installed, it is picked up
+automatically.
+
+## Changes
+
+See `CHANGELOG.md`, shipped alongside this file.
+
+## Licence
+
+MIT -- see `LICENSE`.

data/lib/ecoportal/api/common/graphql/auth_service.rb

@@ -25,7 +25,7 @@ module Ecoportal
             def session_token_renewed(host: server, refresh_token: nil)
               unless refresh_token
                 return unless (body = session_token_data(host: host))
-                return unless (refresh_token = body['resfresh_token'])
+                return unless (refresh_token = body['refresh_token'])
               end
 
               session_refresh_token_data(

data/lib/ecoportal/api/common/graphql/client.rb

@@ -56,12 +56,50 @@ module Ecoportal
             @org_id || fetch_env_required('ORGANIZATION_ID')
           end
 
+          # Graphlient/graphql-client build the client-side schema from the server's raw
+          # introspection JSON (GraphQL::Schema.from_introspection -> GraphQL::Schema::Loader).
+          # That loader defines one GraphQL::Schema::InputObject subclass per INPUT_OBJECT type,
+          # but it never calls `has_no_arguments(true)` on the ones whose `inputFields` came back
+          # empty. graphql-ruby then warns (and, in a future version, raises) the first time
+          # anything asks such a type for its arguments -- which happens whenever this schema is
+          # re-serialized (e.g. `schema.to_json`/`to_definition`, as the `-graphql-schema` use
+          # case in eco-helpers does). The live server never emits this warning because its own
+          # schema classes are defined directly in Ruby with real argument lists (or with
+          # `has_no_arguments(true)` already set) -- it is only the client-side schema, rebuilt
+          # purely from introspection data, that loses that annotation.
+          #
+          # Patching the built classes here (rather than pre-processing the introspection JSON)
+          # keeps the schema's shape untouched and uses graphql-ruby's own documented escape
+          # hatch for this exact situation.
+          def schema
+            mark_argumentless_input_objects!(super)
+          end
+
           private
 
           def url
             base_url = Ecoportal::API::Common::GraphQL::HttpClient.base_url(host)
             "#{base_url}/api/#{org_id}/#{ENDPOINT_PATH}"
           end
+
+          def mark_argumentless_input_objects!(loaded_schema)
+            return loaded_schema if @argumentless_input_objects_marked
+
+            graphql_schema_types(loaded_schema).each_value do |type|
+              next unless type.respond_to?(:kind) && type.kind.input_object?
+              next unless type.respond_to?(:has_no_arguments) && type.respond_to?(:any_arguments?)
+
+              type.has_no_arguments(true) unless type.any_arguments?
+            end
+            @argumentless_input_objects_marked = true
+
+            loaded_schema
+          end
+
+          def graphql_schema_types(loaded_schema)
+            target = loaded_schema.respond_to?(:graphql_schema) ? loaded_schema.graphql_schema : loaded_schema
+            target.types
+          end
         end
       end
     end

data/lib/ecoportal/api/common/graphql/http_client.rb

@@ -96,9 +96,11 @@ module Ecoportal
             end
           end
 
-          ENDPOINT_PATH = 'external/graphql'.freeze
-          READ_TIMEOUT  = 90
-          WRITE_TIMEOUT = 90
+          ENDPOINT_PATH      = 'external/graphql'.freeze
+          CONNECT_TIMEOUT    = 30
+          READ_TIMEOUT       = 90
+          WRITE_TIMEOUT      = 90
+          KEEP_ALIVE_TIMEOUT = 5
 
           attr_reader :host, :version
 
@@ -137,6 +139,36 @@ module Ecoportal
 
           # Creates a HTTP object adding the `X-ApiKey` or `X-ECOPORTAL-API-KEY` param to the header, depending on the API version.
           # @note It configures HTTP so it only allows body data in json format.
+          # @note This is the ONLY place in the gem's dependency chain that talks to the
+          #   server via http.rb (`require 'http'`, pulled in by `Ecoportal::API::Common::Client`
+          #   from the `ecoportal-api` gem) -- every live GraphQL query goes through `#execute`
+          #   below, called from `Logic::BaseQuery#graphql_query` via `client.http_client.execute`,
+          #   and `AuthService#auth_http_client` (`version: 'http'`) reuses this same
+          #   `base_request` for the OAuth token POST. `Common::GraphQL::Client` (graphlient) is a
+          #   separate, unrelated path: it never reaches http.rb at all.
+          #
+          #   Without an explicit `connect:`, http.rb's `HTTP::Timeout::PerOperation` falls back
+          #   to its own default of 0.25s for CONNECT even though read/write were already given
+          #   explicitly (per_operation.rb: `options.fetch(:connect_timeout, CONNECT_TIMEOUT)`,
+          #   `CONNECT_TIMEOUT = 0.25`). `connect_ssl` (`http/timeout/per_operation.rb`) uses
+          #   that same `@connect_timeout` for the TLS handshake via `rescue_readable`/
+          #   `rescue_writable` (`http/timeout/null.rb`) -- whose error text is unconditionally
+          #   "Read timed out after #{@read_timeout} seconds", so a slow TLS handshake on the EU
+          #   instance surfaced as `HTTP::TimeoutError: Read timed out after 0.25 seconds`
+          #   even though `@read_timeout` itself was correctly 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`. Read/write were never the problem; only
+          #   connect was missing.
+          # @note The client is made PERSISTENT (`HTTP.persistent`) to `base_url`, not a
+          #   plain one-shot client. Confirmed live 2026-09-08: eu.live.ecoportal.com
+          #   closes an HTTP/1.1 request carrying `Connection: close` -- what a
+          #   non-persistent http.rb client always sends -- without ever responding. A
+          #   persistent client sends `Connection: keep-alive` and reuses the TCP/TLS
+          #   connection instead, which the SAME Ruby stack proved fine against EU. This
+          #   also matches Cloudflare keep-alive hygiene; Sydney is fine either way. One
+          #   `HttpClient` is bound to one `host`, so `HTTP::StateError` (raised only on a
+          #   cross-origin request against a persistent client) cannot occur here.
           # @return [HTTP] HTTP object.
           def base_request
             @base_request ||=
@@ -151,9 +183,10 @@ module Ecoportal
                 HTTP.headers('Authorization' => "Bearer #{session_token(host: host)}")
               end.then do |request|
                 request ||= HTTP
-                request.accept(:json).timeout(
-                  read:  READ_TIMEOUT,
-                  write: WRITE_TIMEOUT
+                request.persistent(base_url, timeout: KEEP_ALIVE_TIMEOUT).accept(:json).timeout(
+                  connect: CONNECT_TIMEOUT,
+                  read:    READ_TIMEOUT,
+                  write:   WRITE_TIMEOUT
                 )
               end
           end