ecoportal-api-graphql 1.3.17 → 2.2.1

data/CHANGELOG.md

@@ -2,24 +2,776 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.3.17] - 2026-09-30
+## [2.2.1] - 2026-09-30
 
 ### Security
 
-- Security republish of `1.3.16` -- backwards-compatible, no code change: removes customer and
-  internal identifiers from shipped comments and this changelog; stops shipping internal
-  files (packaging allowlist: only `lib/**/*.rb` plus the named root docs ship, so the internal
-  `CLAUDE.md` files under `lib/` no longer do).
+- 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).
 
-## [1.3.16] - 2026-08-13
+### Fixed
+
+- **Fixed:** `api.permissions` (`Query::Permissions`) failed against live after the 2026-09-29
+  platform release, which removed `Permissions.pageSmartAssistantCanChat` and
+  `Permissions.registerAssistantCanChat` (smart-assistant consolidation). `Fragment::Permissions` no
+  longer selects them. The model accessors are kept, deprecated, and now always return `nil`, so
+  callers do not break. Affects every earlier version, including 2.2.0.
+
+### Added
+
+- **Added:** `WorkflowCommand` builder for `moveSectionToStage` (new in the 2026-09-29 live schema):
+  `build(:moveSectionToStage, source_stage_id:, target_stage_id:, section_id:, anchorId:, anchorPosition:)`,
+  moving an existing section to another stage. `anchorPosition` is validated like the other anchor commands.
+
+## [2.2.0] - 2026-09-02
+
+★ **This release supersedes 2.1.0, which was version-bumped and changelogged on 2026-08-21 but never
+tagged or published** — RubyGems' highest was still 2.0.0. Do not go looking for 2.1.0; it does not
+exist as a gem. Its contents are included below by inheritance (they were already on `main`), and
+2.2.0 adds what landed after that bump. Publishing the 2.1.0 artifact would have shipped a state
+already superseded by merged `lib/` fixes and required a second release immediately.
+
+**Minor, not patch:** `Input::WorkflowCommand::AddSelectFieldOption.build` now REQUIRES a `value:`
+keyword. Under the versioning convention (minor = breaking, patch = compatible) that is breaking,
+even though the omitted argument meant the old call shape was already rejected by the server — a
+caller adapting to this is changing working-looking code.
+
+### Added
+
+- `tools/template_yaml/yaml_to_raw_json.py` -- a small, self-contained YAML-to-raw-JSON bridge
+  (inlines the BSON-aware `EpLoader`/`load_dump` the retired Python projector used) so a template
+  backup YAML attached to a ticket can still be fed to the Ruby CLI, which only ever reads JSON.
+  Drops `update_histories` by default (churn neither projector read, and a recurring source of
+  corrupted ObjectIds), with `--keep-churn` to keep it.
+
+
+- **`Page#all_tags` / `Stage#all_tags` read side** (`Model::Page::Phased`, `Base::Page::Phased::Stage`,
+  `Interface::BasePage`): the compiled tag set for a page or a single stage, folded client-side from
+  the page's `baseTags` and the stage's own tags, with both fetched by the page fragments
+  (`Fragment::Page`, `Fragment::Pages::CommonPageUnion`). `Stage#page` now resolves through the
+  native `DoubleModel` root reference rather than a hand-rolled back-pointer, and `location_ids`
+  is redirected page -> stage accordingly.
+
+  ★ This code was written on 2026-07-06 and then sat on three unmerged local branches for seven
+  weeks. `main` never received it in any form, and no other trace of it exists in history --
+  deleting those branches during a sweep would have lost a spec-covered feature permanently. It is
+  cherry-picked here onto current `main` rather than merged from the branch: `main` has since
+  changed four of the five files involved, so taking the branch's copies wholesale would have
+  reverted shipped fixes. That is the stranded-work failure mode this repo has a root-cause note
+  about, caught this time only because a branch sweep asked what each unmerged branch actually
+  contained.
+
+- `tools/template_yaml/forces_walker.rb`: Ruby port of the template projector's `project_forces` /
+  `script_identifiers` (P4), classifying each binding as a FIELD or a SECTION target rather than
+  conflating the two, and reporting the unread force-level `globalBindings` gap as unverified
+  instead of as a finding. Gated by `tools/template_yaml/compare_forces.rb` against the Python IR.
+
+- `tools/template_yaml/review.rb` / `update_gate.rb`: Ruby port of the template projector's
+  `review` / `update_gate` (P5), refusing a template's bulk update PER TEMPLATE (not per field)
+  when no field carries a usable identifier or identifiers are non-unique. Adds a Ruby-only
+  `ximport` tooltip guard: fields marked exclude-from-import are counted and protected, never
+  treated as overwritable. `Delta.call`'s `reviewer:` seam is now wired to `Review.method(:call)`,
+  so `review_findings` appears in the delta payload. Gated by `tools/template_yaml/compare_gate.rb`
+  against a customer's 18 templates -- refusal set matches the Python exactly.
+
+- `tools/template_yaml/model.rb`: Ruby port of the template projector's `project(doc, source)` 
+  (P3's IR assembly), composing field and force walks into a compact IR dict with key order
+  matching the Python prototype for P8 differential acceptance.
+- `tools/template_yaml/render_markdown.rb`: Ruby port of `render_markdown(model, findings)` (P7),
+  rendering a template and its review findings as Markdown with all Python quirks reproduced
+  verbatim: the dead `stage` column, escape-then-truncate on `label`, redundant `type` re-split,
+  CRLF-to-LF normalization on force scripts, and preserved literals like `'(unnamed)'`,
+  `'(no custom script)'`, `'(none)'`.
+- `tools/template_yaml/cli.rb`: Ruby CLI entrypoint matching Python's `main()` (P7), supporting
+  single-file and directory modes, `--out`, `--json`, and `--delta` flags. **Input is JSON 
+  (`*.json`), not YAML**, per Loader's design (see loader.rb header). File writes are LF-only
+  on all platforms via binary mode. Directory mode processes `*.json` files alphabetically,
+  accumulates an `_index.md` at the end, and leaves earlier files on disk if an error occurs
+  mid-run (no transactional cleanup).
+
+- `tools/template_yaml/differential_gate.rb`: P8, the template-yaml Ruby port's acceptance gate.
+  Regenerates BOTH IRs fresh in one run -- Ruby in-process (`Loader` -> `Model.build` -> `Review`
+  -> `UpdateGate`) over the `*.json` corpus, Python via a single batched subprocess (direct
+  import of `ep_template_yaml.py`, not its CLI) over the `*.yaml` corpus -- and diffs the ENTIRE
+  IR: every template attribute, every field, every force (incl. bindings), every review finding,
+  and the `update_gate` refusal set. Live run over a customer's 18 templates: **`P8 GATE: PASS`**,
+  0 unexpected divergences, 12 expected (the six known-corrected ObjectIds, each seen twice --
+  once as a field id, once as a binding `reference_id`).
+- `tools/template_yaml/known_divergences.rb`: the six-id whitelist and its `corrupted_id?` rule,
+  extracted out of `compare_fields.rb` so P3's gate and the new P8 gate share one definition
+  instead of two copies drifting apart.
+- Fixed a Ruby port defect in `review.rb`, found live by the P8 differential run: finding
+  `detail` text quoted force/binding/field names with Ruby's `String#inspect` (always
+  double-quoted) where the Python source uses `%r` (CPython `repr()`, single-quoted by
+  default). Added `Review.py_repr` to reproduce Python's exact quoting.
+- Excluded `patch_ver` and `updated_at` from P8's template-attribute comparison, alongside the
+  pre-existing `source_file` exclusion: the `templates_yaml`/`templates_json` fixture corpora
+  under `tmp/mns_01_tooltip_update/` are two separate exports pulled two days apart (confirmed
+  by file mtime), so these two pass-through fields legitimately disagree -- a corpus-provenance
+  artifact, not a port defect. `compare_fields.rb` / `compare_forces.rb`'s existing 0-unexpected
+  results already proved field/force content is identical across the two pulls.
+
+### Changed
+
+- **Changed** what a failing query prints. `Logic::BaseQuery`'s rescue used to `pp kargs` /
+  `pp query_params` / `pp block` to **stdout** on every error. That existed for a real reason —
+  graphlient masks the origin, so it was the only way to see which query failed — but it put GraphQL
+  variables (page ids, emails, field values) on stdout and into CI logs. Ruby populates `.cause` when
+  raising inside a rescue, so the original error keeps the source location `graphql-client`
+  deliberately sets: the report now names `err.cause`'s class and **the failing query's own source
+  location** on **stderr**, which is more of what the dump was for. Variables are emitted only when
+  the client's existing `deep_logging` flag is on; `pp block` is dropped. A blank message (which
+  graphlient's `GraphQLError#to_s` can render) is now labelled instead of printing nothing.
+  Tracked as Q-43.
+
+### Fixed
+
+- **Fixed** `currentOrganization.pageActivities` returning nothing. The wiring in
+  `Model::Organization` injected `base_path: ['currentOrganization']`, which overrides the
+  `base_path 'currentOrganization.page'` declared by `Query::PageActivities` — so the client
+  dug `currentOrganization.activities`, a path the emitted document never contains (the
+  inline-fragment `activities` merges into `page`). Added `subpath: 'page'`, plus a spec that
+  compares every wired query's declared base_path against the one the wiring injects, so the
+  whole class of bug is guarded rather than the one instance. Tracked as Q-13.
+
+- **Fixed** `Common::GraphQL::ResponseError` discarding `errors[].extensions`. It now carries the
+  raw error entries and exposes `#errors`, `#extensions`, `#codes`, `#details`, `#full_messages`
+  and `#unauthorized?`. This is what makes a permission problem distinguishable from a request
+  problem in Ruby — the diagnosis a customer integration pack tells customers to perform, which until now no tool
+  built on this gem could actually follow. The message still LEADS with the joined server messages
+  (existing matchers keep working) and appends `code:` / `details:` after them. `tools/<customer>/cli.rb`
+  now reports the server's own classification instead of sniffing the message for `/unauthoriz/i` —
+  a sniff that could not tell a policy refusal from a FIELD-level gate. Tracked as Q-27.
+
+- **Fixed** `Payload::Kickstand::BulkUpdateJobs` and `BulkUpdateWorkflows` raising `NoMethodError`
+  on `#items` and `#errors`. Both called `from_doc`, which is a per-class convention in this gem
+  (only 7 classes define one) and does not exist on `Base::Kickstand::Job`/`Workflow` or on
+  `Error::ValidationErrors`. Any caller reading the result of a Kickstand bulk update crashed.
+  Replaced with the real constructor, `new(doc)`. These two classes had **no spec of any kind** —
+  that is why it shipped — so this adds the missing coverage (12 examples over both, shared) as
+  well as the guard. Found while mapping the client's failure surface for Q-31.
+
+- **Packaging allowlist is now keyed on the full path, not the root directory.** `spec.files`
+  previously allowed anything under `lib/` or `exe/`, which packaged five `CLAUDE.md`
+  agent-instruction files living inside `lib/` (573 files now ship, down from 578). The
+  publish-time gate in `scripts/release_smoke_check.rb` had the same hole -- it exempted `lib/`
+  wholesale, so it could not see them by construction. Both now require every packaged path to
+  match `lib/**/*.rb`, `exe/*`, or one of the three named root docs, and the rule is pinned by
+  `spec/packaging_spec.rb` (15 examples, including one that proves the excluded files remain
+  tracked in the repo). No credentials or customer data were ever affected.
+
+- **Seven workflow-command input builders were silently discarding arguments the backend accepts.**
+  Each builder filters its keyword arguments through an allowlist with `kwargs.slice(*KEYS)`, so a
+  key missing from the allowlist is dropped before the request is built: no error, no warning, no
+  effect. The mutation succeeds and does nothing.
+
+  | command | argument restored |
+  |---|---|
+  | `addSelectFieldOption` | `value` — ★ `required: true` on the backend, so **every call this builder produced was rejected by the server** |
+  | `editSelectFieldOption` | `value` |
+  | `editFieldConfiguration` | `required`, `hiddenOnReports` |
+  | `editTemplateBasicSettings` | `enableCopyPage` |
+  | `EditFieldConfiguration::PlainText` | `multiline` |
+  | `EditFieldConfiguration::ContractorEntities` | `applyPermissionsToParent` (distinct from `applyAttachedContractorsPermissionsTo`, which was already present) |
+  | `editForce` | `lastSyncedAt` |
+
+  Found by comparing all 123 command-bus inputs against the backend Rails source rather than
+  against the gem's stored introspection snapshot — that snapshot is dated 2026-07-30, does not
+  show these arguments, and would have confirmed the wrong answer. 104 commands were verified
+  clean. Every restored key is now pinned by a spec asserting on the OUTPUT of `build`, and three
+  of the affected classes had no spec file at all before this, which is a large part of how the
+  drift survived.
+
+- **`Diff::Change` and the template-builder options DSL now carry an option's `value`.** Making
+  `value` required on `AddSelectFieldOption.build` exposed that two production paths never had one:
+  `Builder::TemplateBuilder#emit_options` and `Diff::CommandSynthesizer#option_command`. Neither had
+  ever been able to emit a valid `addSelectFieldOption`; the specs that passed were pinning a
+  command shape the server rejects. `VersionDiff#index_options` now captures `o['value']` alongside
+  label and weight — the field was already being fetched by the page-content fragment and thrown
+  away by the diff layer. Where no value is available, both paths **raise** naming the option and
+  field: `value` is documented as cast to a number for numeric select fields, so defaulting it to
+  the label would silently store wrong data on precisely the scored fields that matter.
+
+- Corrected a false comment in `add_field.rb` asserting that a field's `required` flag "cannot be
+  persisted through the workflow command bus at all". It can, via `editFieldConfiguration`. A
+  comment stating a platform limitation that does not exist is worse than no comment: it stops
+  people trying.
+
+### Removed
+
+- `tools/template_yaml/ep_template_yaml.py` and `tools/template_yaml/mns_review.py` -- the
+  original Python template-backup projector and its cross-template audit. P9 of the template-yaml
+  Ruby port: the Ruby port (`model.rb`, `review.rb`, `update_gate.rb`, `render_markdown.rb`,
+  `cli.rb`) was proven byte/field-parity-identical to both by the P8 differential gate
+  (`differential_gate.rb`, 0 unexpected divergences over 18 live templates) before removal, and
+  the last remaining live use case -- a Jira ticket's YAML-only attachment (EPT-1872) -- was
+  re-verified against the promoted bridge (`yaml_to_raw_json.py`) with byte-identical
+  Python/Ruby deltas. Recoverable in full: `git show
+  0caa6f3d80c6495a9f92132178b9a6a42deb40f5:tools/template_yaml/ep_template_yaml.py` (and the same
+  path for `mns_review.py`).
+
+## [2.1.0] - 2026-08-21
+
+Everything accumulated on `main` since `v2.0.0` (2026-08-13): 150 commits touching 73 files under
+`lib/`. **Minor, not patch:** the bulk is additive -- new data-field models, the last command-bus
+command, a native people-directory query, template-change-log reading -- and 73 library files is not
+a patch by any honest reading. **Minor, not major:** no surface was removed or reshaped, so `~> 2.0`
+consumers adopt it without a floor change.
+
+★ Why this release exists at all, beyond the contents: a remote clone installs PUBLISHED gems, so
+until this went out none of that work could reach the api runner -- and `main` could not be released
+either, because its version constant still read `2.0.0`, which `rake release:check` correctly refuses
+as already published. Three weeks of library work with no route to a remote is the failure mode this
+closes.
+
+
+### Added
+
+- **Wired the `manageCopyPageConfiguration` workflow command** (`Input::WorkflowCommand::ManageCopyPageConfiguration`,
+  first observed in the live schema 20260819): controls `overridePageCreatorPermissions`,
+  `autoIncludeNewContent`, and per-data-field `inclusionSettingsChanges` (`dataFieldId` /
+  `include` / `enforce`) for copy-page behaviour. Closes the last gap in the command bus --
+  `validate-queries` now reports 106/106 commands wired.
+
+- `tools/<customer>/collection.rb` -- a pure-Ruby, stdlib-only read interface over a customer's Postman "ALL
+  CASES" master collection (the sibling `ep-api-collections` repo masters it; this gem never
+  hand-copies its knowledge). Walks the folder tree, exposes each GraphQL request's full path,
+  name, query, parsed variables, and `{{placeholder}}` inventory, with a name/path lookup that
+  tolerates a folder-path prefix and raises a named error listing near-matches when nothing
+  resolves. `spec/tools/<customer>/collection_sync_spec.rb` pins the webhook-admin and build/update-page
+  request paths plus the placeholders the tooling depends on, and fails -- naming exactly what
+  disappeared -- if the collection renames or removes one of them; it skips cleanly (not fails)
+  when no sibling checkout is present. See `tools/<customer>/README.md`.
+
+- `tools/template_yaml/mns_review.py` -- cross-template audit over a directory of IR projections:
+  identifier coverage, `templateContainerUid` uniqueness and name plausibility, findings by code,
+  authoring-maturity signal, and classification of orphaned force bindings into projector gaps
+  versus real defects (checked against the source dumps). First run recorded in
+  `tools/template_yaml/reviews/2026-08-09-<customer>-18-templates.md`.
+
+- **`tools/<customer>/cli.rb`** -- a Ruby CLI that creates/lists/destroys a customer's webhook
+  subscription and verifies the setup read-only, runnable from a support server with nothing
+  but `USER_EMAIL`/`USER_PASS` supplied (every other value defaults to a customer UAT org, EU
+  instance). `webhook create` is idempotent in practice: it lists first and reports the
+  existing subscription instead of creating a duplicate when one already matches the URL and
+  template(s). `--dry-run` prints the GraphQL document and variables with no network call.
+  Document builders live in `tools/<customer>/webhooks.rb` (`<Customer>Webhooks::Documents`) as pure
+  functions, spec'd in `spec/tools/<customer>/webhooks_spec.rb` with no network involved.
+
+- **`Query::PersonMembers`** — the GraphQL-native people-directory path over
+  `organization.personMembers`, filling the gap flagged in `model/organization.rb`. Salvaged
+  from a stranded July branch (`feat/scim-apiv0-adapter-design`) whose SCIM design and
+  scaffold were superseded by the `ecoportal-scim` gem's `apiv0-people-adapter` project; this
+  query was the only part of it with no equivalent anywhere. ★ It is NOT the SCIM-sourced
+  People replacement for the APIv0 retirement — that port lives in `ecoportal-scim`.
+  Reuses the existing `Base`/`Model`/`Connection::PersonMember` classes; no new models.
+
+- `scripts/release_smoke_check.rb` — pre-push gate for BUILT gem artifacts (any gem in the
+  stack): packaging allowlist, byte corruption (`\r\r`, BOM, mixed EOL), and corruption-class
+  parse warnings via `ruby -wc`. Proven against real defects: red on eco-helpers 3.2.21
+  (shipped `\r\r\n`) and on the first 3.2.22 build (CHANGELOG `\r\r` via autocrlf smudge),
+  green on the corrected artifacts. Run it on every `.gem` before `gem push`.
+
+- **Template change log now reports WHAT changed**, not only who/when/which-resource. New
+  registered fragment `:TemplateChangeLogEntryDetail`, opt-in via
+  `api.template.change_log(id:, first:, detail: true)` or
+  `&Query::TemplateChangeLog.detail_block`. The default selection is unchanged and still light —
+  the common "who touched this template and when" read does not pay for per-type detail.
+  `Base::Template::ChangeLogEntry` gains `#changes`, `#changeMessages`, `#detail_kind`
+  (`:changes` / `:change_messages` / `:es_changes` / nil) and `#detail?`.
+  ★ The three concrete command types report changes in three different shapes, so `#changes`
+  returns raw hashes rather than a typed embed that would have to lie about one of them:
+  `PagesWorkflowCommandChange.changes` is `{field, from, to}` with STRING values;
+  `PagesWorkflowCommandEsChange.changes` has `from`/`to` as `StoredEsFilterType` OBJECTS (only
+  `field` is selected, so an ES change names which filter moved, not its before/after);
+  `PagesWorkflowCommandChangeMessage` carries pre-rendered `changeMessages` and no field/from/to.
+  Branch on `#detail_kind`. ★ Empty readers mean NOT SELECTED, never "nothing changed".
+
+- **Template change log (GraphQL-native)** — `Query::TemplateChangeLog` reads the platform's
+  per-change audit log for a template: "for template X, who changed what and when", newest first,
+  paginated. Reachable as `api.template.change_log(id: template_page_id, first: 50)`, or bare
+  (`api.template.change_log.each(id: …)`) for an auto-paginating enumerator.
+  Read path: `currentOrganization.page(id:) → template → commands` — `template` is declared on
+  `BasePageInterface`, so it is selected through a type condition (selecting on the returned
+  `PageUnion` directly is invalid GraphQL). New supporting types:
+  `Base::Template::ChangeLogEntry`, `Model::Template::ChangeLogEntry` (adds the `owner` embed —
+  WHO changed it), `Connection::TemplateChangeLog`, and the registered fragment
+  `:TemplateChangeLogEntry` on the interface `PagesWorkflowCommandInterface`.
+  ★ Two access caveats, both silent and both documented on `Base::Template::ChangeLogEntry`:
+  (1) the connection is **nil, not empty**, unless the caller satisfies
+  `Pages::TemplatePolicy#update_information?` — a read-only account sees no log and no error, so
+  never read nil as "nothing changed"; (2) the server scope is `from_template_builder`, so only
+  `TEMPLATE_BUILDER`-sourced commands appear — `WORKFLOW_BUILDER` changes to the same page are
+  excluded (those are on `Query::PagesWorkflowCommands`).
+  ★ Why this beats polling a watermark: a forces run writes with `skip_patch_incr` + `timeless`,
+  bumping **neither `patchVer` nor `updatedAt`** — any watermark-polling change tracker is blind to
+  force-driven change, whereas the command log is per-change. (Open: whether forces run against
+  templates specifically is not confirmed.)
+  Also documented in the repo's internal docs.
+
+- **New tool `tools/template_yaml/delta.rb`** (P6 of the template-YAML-tooling Ruby port): the
+  deterministic before/after difference between two `project()` snapshots, shaped for the Rovo
+  delta-verification agent. Field pairing on id-then-identifier (so a REBUILT field -- new id,
+  same `description` -- is one `changed` entry rather than an add/remove pair), `TRACKED`-only
+  attribute diffing, force diffing by name with binding set-difference, the five-key template
+  diff, and the four `not_evaluable` strings reproduced VERBATIM, because the Rovo agent is
+  instructed to read that list literally and any wording drift changes what it is told it cannot
+  verify. **Verified against the canonical Python on the known pre/post pair (all 7 comparable
+  sections identical) and on 9 synthetic scenarios covering every branch -- rebuild, removal,
+  untracked-only change, template attributes, force add/remove/script/binding-set-diff, and
+  reference-id-only binding moves -- 0 mismatches.**
+- **`Delta::Result` reports what the pairing could not say cleanly** -- colliding pairing keys,
+  duplicate force names (only the last is diffed), and rebuild pairings -- rather than returning
+  a bare hash the way the Python does. `review_findings` is **omitted** from the payload until a
+  reviewer is injected (it re-runs `review()`, which is P5): emitting an empty list there would
+  read as "no findings" when the truth is "not checked".
+- **Corrected `P1-CONTRACT.md` section 8.** It claimed `_key` can return `None` and that fields
+  with neither id nor description are "filtered out of both snapshots entirely ... invisible to
+  `delta` by construction". Verified by running the Python: `'ref:' + ''` is truthy, so the
+  `or None` branch is unreachable and `_key` never returns `None`. Those fields are not filtered
+  out -- they all collapse onto the single key `'ref:'`, so an unidentified field in `before`
+  pairs with an **unrelated** unidentified field in `after` and their differences are reported as
+  a change. Not a live defect (every membrane in the JSON export carries a validated hex `_id`),
+  but a latent trap; the port reproduces it for parity and warns on it.
+
+- **New tools `tools/template_yaml/field_walker.rb` + `tools/template_yaml/compare_fields.rb`**
+  (P3 of the template-YAML-tooling Ruby port): enumerates a template's fields in on-screen
+  LAYOUT order -- `flow_nodes` by `weight`, then `membrane_ids` / `left_membrane_ids` /
+  `right_membrane_ids`, then each id list in stored order -- porting the Python projector's
+  `walk_fields` against the contract frozen in `P1-CONTRACT.md`.
+  **Verified against the real 18-template customer dump set: 2,714 fields, ids and ordering match the
+  Python projector exactly, with 0 unexpected divergences.** The only 6 differences are the
+  `ActionsList` ids the Python's YAML path corrupts (a contiguous run of `ActionsList` ids), where
+  the Ruby is correct and the Python is not; `compare_fields.rb` whitelists those six BY VALUE,
+  so a seventh divergence -- or any ordering defect on that same template -- still fails.
+- **`FieldWalker` distinguishes "no fields" from "could not see the fields"**, which the Python
+  cannot: it returns a `Result` carrying the faithful field list plus every membrane it dropped,
+  every layout reference it could not resolve, duplicate placements, non-hash nodes and
+  defaulted weights, with `#blind?` true exactly when an empty list is untrustworthy. A
+  command-bus-built template with no layout, a `SplitSection` with no `dataFields`, and a
+  genuinely empty template all return an empty or short list from the Python with no error; they
+  are now told apart. Three port-critical quirks are preserved deliberately and covered by
+  specs: Python truthiness in the `or` chains (an empty `heading` must fall through to
+  `left_heading`, an empty `_type` must stay `''` -- `''` is truthy in Ruby), the STABLE node
+  sort (`Array#sort_by` is not stable), and `bool`-is-`int` weights.
+
+- **New tools `tools/template_yaml/loader.rb` + `tools/template_yaml/id_guard.rb`** (P2 of the
+  template-YAML-tooling Ruby port): loads an ecoPortal template backup dump from its **JSON**
+  export -- not the YAML -- and validates every id-shaped value against `/\A[0-9a-f]{24}\z/`,
+  raising loudly (template, field path, offending value) rather than letting a bad id through.
+  Reading JSON instead of YAML is deliberate: the Python projector's YAML path decodes
+  `!ruby/object:BSON::ObjectId` via a step with a silent-failure mode (confirmed unchanged on
+  the canonical post-!86 surface in `P1-CONTRACT.md`) that corrupts 6 of 2,432 fields on one
+  customer template without affecting counts. The JSON export carries identical data with plain hex
+  ids already, so the whole decode-bug class is structurally impossible on this path rather
+  than reimplemented. Verified against the real 18-template customer JSON dump set, including the 6
+  previously-corrupted `ActionsList` ids on "Yard 5S Site Standard"
+  (a contiguous run of `ActionsList` ids), which load and validate correctly.
+
+### Changed
+
+- **`ecoportal-api-v2` floor raised to `>= 3.3.5`** (was `>= 3.3.3`). 3.3.5 carries the fix for
+  `ClassHelpers#to_time`, whose rescue clause named a constant that does not exist
+  (`ArgumentArgument`), so its documented `exception: false` mode raised
+  `NameError: uninitialized constant ...ClassHelpers::ArgumentArgument` instead of returning nil.
+  This gem inherits that helper through DoubleModel, so any null or object-shaped date reaching a
+  `passdate` field hit it. ★ Side benefit: the old floor pointed at **3.3.3, which was yanked**
+  for shipping internal repository content to rubygems — a floor should not name a yanked version.
+
+### Fixed
+
+- `FieldConfig::CrossReference` could not set `enableCrossRegisterReporting` (Boolean) — the schema
+  accepts the key but no builder path could reach it. Closes the last MISSING-key advisory reported
+  by `tests/validate_commands.rb` for the `crossReference` byType key.
+
+- Stripped UTF-8 BOMs from 58 `lib/` source files (present since early development; harmless
+  to Ruby but flagged by the release smoke gate, and byte-noise for every downstream diff).
+
+## [2.0.0] - 2026-08-13
+
+Major release: everything accumulated on `main` since `v1.3.14` — the 2026-07-13/07-25/07-31
+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` 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.
+
+★ **What starts WORKING when you adopt this** (silently-broken → live, coming from ≤ 1.3.14):
+the page-level `executeWorkflowCommands` bus, File-field attach writes, `updatePresetView`
+column edits, AI-summary mutations, viewable-field management, Date-field renewals, and
+eco-helpers' `OozeRedirect` force path (always errored before — re-verify on a sandbox org
+before trusting it in a customer run). Review those paths before assuming a no-op upgrade.
+
+Note: this release does not descend from `v1.3.15`, which shipped from the `release/1.3.15`
+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-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.
+
+### Added
+
+- `WorkflowCommandInput` commands: `editTemplateBasicSettings`, `editTemplateAdvancedSettings`,
+  `editTemplateCreatorPermissions`, `editTemplateDescriptions`, `createPublicConfig`,
+  `editPublicConfig`, `archivePublicConfig`, `addChecklistFieldItem`, `editChecklistFieldItem`,
+  `removeChecklistFieldItem`, `addSmartFillConfig`, `editSmartFillConfig`, `removeSmartFillConfig`.
+- `addStage` gained `tags` (create a stage already tagged).
+- `editFieldConfiguration` gained `addActionIds`/`removeActionIds`; `crossReference` gained
+  `addReferenceIds`/`removeReferenceIds`; `imageGallery` gained `addImageSourceIds`/`removeImageIds`;
+  new `file` by-type field config (`addFileContainerIds`/`removeItemIds`).
+- **The WorkflowCommandInput command bus is now at full coverage: 105/105 commands, 14/14 field-config
+  builders, zero dead keys, zero unreachable keys** — verified against the live `20260731` schema.
+  Granular template management no longer has holes.
+- **`tests/validate_commands.rb`** — new offline gate, the command-bus sibling of
+  `validate_queries.rb`. That gate can only see the documents we *send*; every command travels as a
+  member of a `[WorkflowCommandInput!]` **variable**, so unwired commands and stale key allow-lists
+  were completely invisible to it. The new script reports unwired commands, dead keys (gem sends,
+  schema rejects), orphaned `COMMAND_MAP` entries, missing keys, and byType builder coverage.
+  Fails the build on the first three. Wire it into CI next to `validate-queries`.
+- **`addViewableField` / `moveViewableField` / `removeViewableField` commands** — these replaced
+  `WorkflowEditFieldConfigurationPeopleInput.addViewableFields`/`removeViewableFields`, which the
+  20260725 drift REMOVED. Between that drift and now, viewable-field management was impossible
+  through the gem: the old keys were dead and the new commands were unwired. The replacement also
+  adds ordering (`anchorId` + `anchorPosition`) the flat arrays could not express.
+- **`Input::WorkflowCommand::EditFieldConfiguration::ActionList`** — the 14th and last unwired
+  `byType` member, so ActionsList field configuration is reachable at last.
+- **`updateRelatedPage` mutation** + payload + `Builder::Template#update_related_page`. The worklog
+  carried this as an *ecoportal backend* gap ("the only genuine structural template omission") — that
+  was stale, the mutation is in the live schema, so the gap was ours. Related-pages entries could be
+  created and destroyed but never edited, forcing destroy+recreate for a title change, which
+  discards the entry id.
+- **Cross-version template identity is now readable.** `CommonPageUnion` selects
+  `template { templateContainerUid active }`, and `Interface::BasePage` exposes `#template`
+  (a read-only `Model::Template::Information`) plus the `#templateContainerUid` shortcut.
+  `templateContainerUid` is the template **series** key: many versions may carry the same value,
+  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 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
+  `3-20 chars, [a-zA-Z0-9-_.]` format up front.
+- **DataField `description` is now readable.** Added to the `dataFieldInterface` fragment and
+  declared `read_only: true` on `Base::Page::DataField`. It is the hidden per-field note that
+  integrations reuse as a pseudo external-id on fields. Read-only is deliberate: `description`
+  exists on `DataFieldsInterface` but on no member of `DataFieldInput`, so a writable accessor would
+  dirty the field and push a key `updatePage` cannot accept — the only writer is the
+  `editFieldConfiguration` workflow command, which is confirmed to work on **page instances** as
+  well as templates.
+- `tests/page_field_description_update.rb` — scripted read-modify-verify for a single dataField
+  `description` on a page instance, with a `--dry-run` mode and a `canRestructure`/`canConfigure`
+  pre-flight.
+- **`Diff::Pairing::Signals.genome` now recognises lineage ancestry** (scores `0.9`, just below
+  an exact match) when one signature is a strict prefix of the other. Verified live 2026-08-05
+  on a same-org restore of a full template backup: a restore re-mints every Mongo id and
+  APPENDS one segment to every membrane AND force genome signature (28/28 + 4/4 followed the
+  rule, e.g. `ktnrya` → `ktnrya877l`) — equality-only scoring handed the exact cross-object
+  case the pairing engine exists for (UAT backup → PROD restore) a `0.0` mismatch. Signatures
+  shorter than 4 chars are rejected as ancestry evidence (chance-collision guard).
+- **New manual tool `tests/template_backup_diff.rb`**: loads the platform's template BACKUP
+  files (YAML = Mongoid/BSON object dump — loaded via shims, no bson dependency; JSON = same
+  document, ids as hex/times as ISO8601), converts YAML→JSON, and produces an id-keyed deep
+  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 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,
+  verified inventory of existing tooling, the two shared primitives the set is missing (field
+  identity across template versions, and a versioned table projection), staged plan through to
+  promotion into its own repo, and the open blockers.
+
+### Added (read-model / type layer — additive, non-breaking)
+
+- **System access logs:** `Base::AuthLog` / `Model::AuthLog` (+ `Connection::AuthLog`, `:AuthLog`
+  fragment) and `Model::Organization#authLogs` (`Query::AuthLogs`).
+- **Changelog history:** `Base::PersonMemberChangelog` / `Model::PersonMemberChangelog`
+  (+ `Connection::PersonMemberChangelog`, `:PersonMemberChangelog` fragment),
+  `Model::Organization#personMemberChangelogs` (`Query::PersonMemberChangelogs`), and
+  `Model::PersonMember#changelogs`.
+- **Dashboards:** `Base::MinimalDashboard` / `Model::MinimalDashboard`
+  (+ `Connection::MinimalDashboard`, `:MinimalDashboard` fragment) and
+  `Model::Organization#dashboardSearch` (`Query::DashboardSearch`).
+- **Actions:** `Base::ActionEvent` / `Model::ActionEvent` and `Base::ActionEventPage` /
+  `Model::ActionEventPage`.
+- **RS/location:** read-only `LocationStructure#generating`/`#aiPrompt`,
+  `LocationClassificationType#aiGenerated` (selected in the structure queries + `:LocationNode`
+  fragment).
+- **Contractor:** `updateContractorManagerSettings` mutation
+  (`Mutation::ContractorEntity::UpdateManagerSettings` + `Input`/`Payload::…::ManagerSettings`,
+  exposed as `Builder::ContractorEntity#update_manager_settings`) and read-only
+  `Organization#allowContractorAdminsToAddAdmins`.
+- **`Base::AuthorizationResult` / `Model::AuthorizationResult`** (+ `:AuthorizationResult` fragment) —
+  the reusable node type behind the schema's many `canXXX: AuthorizationResult` permission fields;
+  wired `Model::PersonMember#canManageContractorAdmins`. Unblocks the deferred `Permissions`-parented
+  `canXXX` fields (which still await a `Permissions` model).
+- **`Base::Permissions` / `Model::Permissions`** (+ `:Permissions` fragment) — the org-level ability
+  set (`Organization.permissions`). Models all **83** `canXXX: AuthorizationResult!` fields as
+  `embeds_one` (e.g. `dashboardCanManage`, `locationStructuresCanAiGenerateStructure`,
+  `generatedPageFilterCanUseSmartQuery`). Wired `Model::Organization#permissions` (typed embed) plus a
+  native `Query::Permissions` (`currentOrganization.permissions`). The `:Permissions` fragment spreads
+  `:AuthorizationResult` per field (recursively assembled).
+
+### Added (polymorphic activity feeds — the REAL access-logs & page-history fields)
+
+The web "System Access Logs" page and page "history changelog" are driven by
+`currentOrganization.activityLogs` (a UNION) and `page.activities` (an INTERFACE) — NOT the flat
+`authLogs`/`personMemberChangelogs` types. These add the polymorphic read models for the real fields.
+
+- **System Access Logs:** `Base::ActivityLog` / `Model::ActivityLog` (+ nested `Model::ActivityLog::Resource`,
+  `Connection::ActivityLog`, `:ActivityLog` fragment) over the `ActivityLogUnion` (9 members:
+  DashboardAccess/Create/Delete/Update, DeniedDashboardAccess, DeniedPageAccess, FileDownload, PageAccess,
+  ScimIntegrationAccess). Models the fields common to all members + `__typename` passthrough; the Dashboard*
+  members' `parentResource*` + `resource { isVisible: AuthorizationResult }` are nullable embeds. The
+  fragment uses inline fragments per member (spreading `:ActivityLogCommon` on `BaseActivityLogInterface`
+  and `:ActivityLogResource` on `BaseDashboardActivityLogInterface`). Exposed as
+  `Model::Organization#activityLogs` (`Query::ActivityLogs`) with the full filter set
+  (`userIds`, `resourceIds`, `filterSuperusers`, `activityType`, `resourceType: ActivityLogTypesEnum`,
+  `source: SourceEnum`, `dateFilter: DateRange`, cursor pagination). New `Input::DateRange`.
+- **Page history / activities:** `Base::Activity` / `Model::Activity` (+ `Connection::Activity`,
+  `:Activity` fragment) capturing the `ActivityInterface` common fields (id, `__typename`, priority,
+  system, fromPublicTemplate, stageId, categories/subkey, source/user scalars, createdAt/updatedAt,
+  personMember, user) across its ~61 concrete types — an unmodelled type still resolves as a plain
+  `Model::Activity`. Exposed as `Model::Organization#pageActivities` (`Query::PageActivities`) resolving
+  `page(id:).activities(searchConf:, …)`; because `page` returns a `PageUnion`, the connection is selected
+  via inline fragments on BasicPage/PhasedPage (`:PageActivities` + `:ActivityConnection` fragments).
+
+### Changed
+
+- `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 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,
+  `spread(on:)` inline fragments, `fragment(:Name, on:)`, custom scalar registration) — non-breaking,
+  since the gem's own usage of these APIs is unchanged. `Gemfile` git override removed;
+  `ecoportal-api-graphql.gemspec` bound updated `>= 0.8.0, < 0.9` → `>= 0.9.0, < 0.10`.
+
+### Changed (BREAKING)
+
+- `reorderForces` and `reorderSection`: `after`/`before` replaced by `anchorId`/`anchorPosition`.
+- `moveField`: gained `anchorId`/`anchorPosition`.
+- SmartFill removed from `date`/`plainText`/`richText`/`select` field configs — moved to the
+  dedicated `*SmartFillConfig` commands above.
+- **AI summary mutations rewired to the fields that actually exist.** Both targeted mutation names
+  that are absent from every introspection we hold (2026-07-13 and 2026-07-30), so neither ever
+  worked:
+  - `Mutation::AiSummary::Generate`: `generateAiSummary(pageId:, stageId:)` →
+    **`generatePageSummary(input: GenerateInput!)`**. `#query` now takes `page_id:` / `stage_id:`
+    (was `pageId:` / `stageId:`) and wraps them into `input`.
+  - `Mutation::AiSummary::SubmitFeedback`: `submitAiSummaryFeedback(aiSummaryVersionId:, sentiment:)`
+    → **`submitPageAiSummaryFeedback(input: SubmitFeedbackInput!)`**. `#query` takes
+    `ai_summary_version_id:` / `sentiment:`. The enum is `SentimentEnum`, not
+    `AiSummarySentimentEnum`, and its values are **`positive` / `negative`** — the class previously
+    documented "THUMBS_UP"/"THUMBS_DOWN", which the schema has never accepted. `#query` validates
+    the value up front.
+  - `Base::AiSummaryVersion` dropped `prompt`, `inputTokens`, `outputTokens`, `totalTokens`,
+    `resourceType`, `ratings` — none exist on the type; they always read nil. Real fields:
+    `aiSummary`, `alreadyRated`, `createdAt`, `dataFieldLogs`, `generationErrors`, `id`,
+    `pagePatchVer`, `status` (the last three complex ones stay unmodelled until verified).
+
+  _(The `Payload::OkPayload` errors-modelling fix from the same commit is NOT breaking and
+  already shipped in 1.3.15 — see that release's section.)_
+- **`FileUpload::Client` reimplemented natively from a captured web upload** (breaking, but the
+  old path could not work). The real flow — verified from a HAR of the React frontend on
+  2026-07-30, then cross-checked against the live schema — is three steps, all GraphQL except
+  the storage POST:
+  1. `FileSignature` (GraphQL) → presigned policy + credentials
+  2. multipart POST to S3 → `204`; fields in order: `key`, `AWSAccessKeyId`, `policy`,
+     `signature`, `content-type`, `x-amz-server-side-encryption`, `file`
+  3. **`uploadFile` (GraphQL)** → the `FileContainer`, whose `id` page mutations consume
+
+  The previous implementation was a port of `ecoportal-api-v2`'s REST S3 code and did
+  `POST /api/v2/<org>/s3/files` + polling. **The platform does not use those endpoints for this
+  flow** — there is no register-over-REST and no poll — so the 1.3.15 change that made those
+  calls authenticate (`X-ECOPORTAL-API-KEY`) fixed a step that does not exist. No API key is
+  needed for file upload at all; `api_key:` on `GraphQL.new` remains available but unused here.
+  - **New:** `Mutation::FileContainer::Upload` (`uploadFile`), `Payload::Upload`, and
+    `Concerns::Threadable` (bounded concurrency, ported from `ecoportal-api-v2` rather than
+    depended on, since that gem is being decommissioned).
+  - **New: `#upload_all(paths, threads: 4) { |result| }`** — concurrent multi-file upload with
+    per-file error isolation (a single failure never raises out of the batch; each `Result`
+    carries its own `error`/`container_id`), presigning **once** per batch, and a `Result` struct
+    shaped like v2's `S3::Files::BatchUpload::FileResult`. `threads: 1` runs inline.
+  - **New: stage hooks** — `client.on(:signature|:storage|:register) { … }`, chainable, for
+    logging/instrumentation/middleware around each step.
+  - **Fixed: storage keys no longer collide.** The key is
+    `uploads/<userId>/<epoch-ms>-<token>-/<basename>` as the web client builds it; the old
+    `upload_prefix + filename` concatenation meant two uploads of `report.pdf` overwrote each
+    other in the bucket.
+  - **Fixed: `x-amz-server-side-encryption` is read from the policy** (base64 JSON `conditions`)
+    instead of being hardcoded to `AES256` — the value now comes from the same source S3 validates
+    against, with `AES256` only as a fallback.
+  - **Fixed: `Base::FileContainer`** declared `activeVersionId`, which does not exist on the type
+    (it is `activeVersion`) and always read nil; `otherTags` was missing, which matters because
+    `UploadInput.otherTags` is the only way to tag a container — now exposed as
+    `upload(path, tags: […])`.
 
 ### Fixed
 
-- Packaging-only republish of `1.3.15` with an allowlisted gemspec (backported from `2.0.0`).
-  Versions `1.3.9`-`1.3.15` shipped internal repository content (internal AI-tooling project notes,
-  `docs/worklog.md`, architecture docs) to rubygems.org via the old denylist `spec.files`; they
-  will be yanked. `1.3.16` is the identical `lib/` code (including the `1.3.15` OozeRedirect
-  `executeWorkflowCommands` fix) packaged clean, so the `1.x` line keeps a clean latest release.
+- **Cascaded leaf arrays are no longer dropped from `as_update`.** Leaf arrays declared with
+  `passarray`/embeds-many (id-lists, tag-lists, config-lists) were invisible to the diff: the
+  default `DiffService` strips cascaded keys from the flat classic diff, and `diff_reduce` only
+  re-adds children that are a `GraphQL::Model` — an `ArrayModel`/`CollectionModel` is not — so
+  the array change was silently discarded and no mutation was issued for it (SYNTHESIS.md 3.1).
+  The `DataField`-local `LeafDiffService` is promoted to the common layer
+  (`common/graphql/model/diffable/leaf_diff_service.rb`): it keeps cascaded doc keys in the flat
+  diff, preserves the flat-diff placeholder for non-model leaf children while still cascading
+  into real nested models and dropping `root!` children, and treats a leaf array as an opaque
+  full-set replace (no id-keyed nested patch-ops), matching how the write inputs consume these
+  arrays. Set as `DIFF_CLASS` on `Interface::BasePage` (covers Basic + Phased), `Base::Register`
+  and `Base::PresetView`; `Base::Page::DataField` now references the promoted class with
+  identical behaviour. Newly detected: page `otherTags` (full-set replace) and `locations`
+  (`[{id:}]` via `location_ids=`), `Register#filterTags`, and `PresetView#fieldConfigurations`.
+- `Base::PresetView` now emits a schema-valid `updatePresetView` input for its column
+  configuration. The read model exposes the collection as `fieldConfigurations` (the key the
+  API returns), but `UpdatePresetViewInput` calls it `fieldConfigs` **and** takes it as a
+  `FieldConfigurationOneToManyInput` — `{ additions:, deletions:, updates: }` — not as the
+  read list; both facts are schema-confirmed in the live introspection dump (20260730), where
+  the field is also NON_NULL with no default, i.e. required on every call. Emitting the read
+  key would be an unknown-argument error and emitting the read list under the write key would
+  be a type error, either of which rejects the WHOLE mutation, a `name`-only edit included.
+  `#as_input` (and `Input::PresetView::Update.from_model`, which shares the same reshape, so
+  the implicit and explicit converter seams agree) now renames the key, computes the
+  additions/deletions/updates delta directly from `doc` vs `original_doc` — matching configs on
+  their `id` and whitelisting the fields `FieldConfigurationInput` accepts, so the read-only
+  `__typename` is dropped — and always sets `fieldConfigs`, using the no-op `{}` when the
+  columns did not change. A columns-only change is now sent at all: it was previously dropped
+  from the flat diff, so `as_input` returned `nil` and no mutation was issued.
+  `Input::PresetView::Update` declared `fieldConfigs` as a `passarray`; it is now a
+  `passthrough`, matching the object the schema expects. The create path is unaffected —
+  `CreatePresetViewInput.fieldConfigs` is a plain `[FieldConfigurationInput!]!` and
+  `Input::PresetView::Create` already used the write key with the right shape.
+- `Base::Page::DataField::FileField` now reads and writes the shape the live API actually
+  uses. WRITE: `as_input` emits `file: { id:, items: [ItemInput] }` — live `FileInput` has
+  no `fileContainerIds` member, so every File-field write was rejected (live-confirmed
+  2026-08-01 via `pages/file_upload`; the 4-step upload passed, the attach failed). The
+  backend applies `items` as full-replace (any existing item id not echoed back is
+  destroyed), so kept containers are sent as `{ id: <item_id> }` and new ones as
+  `{ fileContainerId: }`. READ: `file_container_ids` now maps `items[].fileContainer.id`
+  (the fragment's actual selection, which now also selects the item `id`) instead of a
+  `fileContainers` doc key the API never returns — reads always came back empty before.
+  BREAKING (dead surface): the `FileField#fileContainers` accessor is gone, replaced by
+  `items`; no consumer existed in this gem or eco-helpers, and it could only ever return
+  empty against real API responses. `file_container_ids` / `file_container_ids=` keep
+  their contract. `ImageGallery` is untouched: its write shape is also invalid, but live
+  `ImageInput` attaches via `sourceId` (an `Enzyme::ImageReference::TempImage`, a
+  different upload pipeline than file containers) — needs its own design, tracked in the
+  DataField shape-asymmetry review.
+- **`People#dirty?`** compares the people-id SET vs `original_doc` (falling back to the
+  `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
+  (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
+  responses never populate — so it always returned `[]` on a freshly-fetched page — and the
+  default leaf diff phantom-dirtied the field the moment any setter ran, even for a no-op
+  restatement or a clear on an already-empty field. Now reads `contractorEntities[].id` with
+  staged-write preference and compares effective id SETS against `original_doc` in `dirty?`
+  (the CrossReference fix template).
+- `Query::Page` now accepts the `CommonPageUnion` document variables (`showHiddenData`,
+  `content`, `only_content`, `fields`) as call params, and `Compat::Pages#get` forwards
+  them (`pages.get(id, content: false)`). Previously `accepted_params :id` silently
+  dropped any override, so the document-level defaults could never be changed.
+  This matters for least-privilege accounts: `attachedFiles @include(if: $content)` is
+  preauthorized on the `files: download` ability, so an account without that grant could
+  not complete **any** page read — found live when the template-tests account
+  (`-space graphql_templates`) had every `pages.get` refused while a minimal hand-written
+  page query succeeded. `content: false` is the structure-only read (template tooling,
+  config audits) and needs no file grant. Defaults are unchanged — no caller impact.
+- **Four `Input::LocationStructure` command bugs are fixed — `add(type, **kwargs)` was broken on
+  every path.** `UpdateCommand#name` / `#classificationIds` called a non-existent `super` (plus a
+  redundant `nil.empty?` guard), raising `NoMethodError`; both readers now fall back to the stored
+  `name` / `classificationIds` so they work with or without a `new*` override. `ApplyCommands` and
+  `Draft::AddCommands` mapped the `:reorder` command type through a typo'd `:reoder` key, so
+  `add(:reorder, ...)` raised `NameError: uninitialized constant ...::ReoderCommand` — reorder was
+  unreachable from either dispatcher. `Interface::LocationStructure::Command#set_values` called the
+  0-arg reader instead of the writer (`#{key}=`), raising `ArgumentError` and breaking the whole
+  `#add` path for every command type, not only reorder. Adds `commands_mapping_spec` (18 examples)
+  covering all four. Note: the typo symbol `:reoder` is no longer in the dispatch table, so
+  `add(:reoder)` now raises `RuntimeError: Unknown command type: 'reoder'` instead of `NameError` —
+  not a breaking change, since `:reoder` never resolved to a real class either way.
+- **`FieldConfig::People` sent two keys the server rejects** — `addViewableFields` /
+  `removeViewableFields`, removed from the schema in the 20260725 drift. Now dropped, and the six
+  keys that drift *added* are reachable: `add`/`removeAllowedUserGroupIds`,
+  `attachedPeoplePermissionsEnabled`/`Editable`/`Flags`, `applyAttachedPeoplePermissionsTo`. The
+  nested flags hash is filtered to the seven declared flags so a stray key cannot sink the command.
+- **`FieldConfig::Date` could not set renewals** — `createEvent`, `remindMeIn`, `renews`,
+  `renewsEvery`, `renewsUnit`, `renewsUntil` were all unreachable. Renewals are how expiry-driven
+  registers (certifications, inductions, permits) are configured, so this was a functional hole
+  rather than a cosmetic one.
+- **`EditFieldConfiguration` silently dropped `stageId`** — required to disambiguate a field on a
+  phased page, which made the builder unusable there; callers had to hand-build the command hash.
+  `addPermittedPersonSchemaIds` / `removePermittedPersonSchemaIds` were dropped the same way.
+- **Connection node-type poisoning.** `Logic::Connection` declared `embeds_many :nodes, klass: :node_class`
+  on the shared base, so the v2 collection layer memoized the first-resolved node class onto the single
+  shared collection — the first connection instantiated in a process poisoned every other connection's
+  instance `nodes` typing (e.g. a `MinimalDashboard` connection returning `AuthLog` nodes), corrupting
+  `QueryConnection#each` pagination when >1 connection type is used per process. Each subclass now binds
+  its own concrete-class collection via the new `Logic::Connection.nodes_of` macro. Regression spec added.
+- `Compat::Response` now validates at construction that its payload honours the response contract
+  (`success?`/`error?`/`error_doc`/`item`), raising `ArgumentError` with the missing methods
+  otherwise. Closes the duck-typing drift class behind the eco-helpers 3.2.19 KPI-counter
+  regression (a non-response object slipping through). +spec `spec/ecoportal/api/graphql/compat/response_spec.rb`.
+- **`main`'s version constant no longer advertises a published release it is not.** `2dad1e4`
+  (2026-08-08) set `GRAPQL_VERSION` to `1.3.15` while raising the `ecoportal-api` floor to
+  `0.10.17`. But `1.3.15` had already shipped nine days earlier from `release/1.3.15` (tag
+  `v1.3.15`, on RubyGems since 2026-07-30), and that tag is **not** an ancestor of `main` — the
+  two lines forked at `21516a3` (1.3.14) and `main` has carried ~200 commits of 1.4.0-track work
+  since. So `main` was building a materially different tree under a published version number,
+  against this repo's "never ship a fix under a published version" convention. The constant was
+  restored to `1.3.14` — the last release `main`'s tree actually descends from — until this
+  release set it to `2.0.0`. The `0.10.17` floor itself is unaffected and ships with this release.
+
+### Removed (BREAKING)
+
+- `WorkflowCommandInput` commands `editPage` and `editPageCreatorPermissions` — removed from the
+  live schema (2026-07-13) and now removed from the gem. `WorkflowCommand.build(:editPage, …)` /
+  `build(:editPageCreatorPermissions, …)` raise `ArgumentError` (unknown key). The
+  `DEPRECATED_KEYS` / `warn_deprecated` machinery on `Input::WorkflowCommand` was removed with them.
+  **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 / 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
+  code) — `smartFillGenerate` and `smartFillSubmitFeedback` **do not exist in the schema**, and
+  never did: the live mutation list has no `*fill*` mutation at all (checked against both the
+  2026-07-13 and 2026-07-30 introspections). SmartFill exists only as *configuration*
+  (`WorkflowCommandInput`'s `add/edit/removeSmartFillConfig`, the `SmartFill*Configuration`
+  types) and as a **read** data field — `Base::Page::DataField::SmartFill` is unaffected and
+  stays. Nothing could have depended on the removed mutations because they always failed; if
+  page-level SmartFill triggering is needed, it has to be added to the platform first.
+
+### Documentation
+
+- `ecoPortal_architecture/10_forces_workflow_builder.md`: operational rules for auditing force
+  bindings — a binding may target a field OR a section; `globalBindings` is a separate collection;
+  a field declaring `global_binding` is present at stage render regardless of its section/stage;
+  backup-YAML ObjectIds are binary so a text search for an id proves nothing.
+- `ecoPortal_architecture/07_data_fields.md`: which subset of fields carries an identifier, and how
+  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%.
+- 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.
+- 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.
 
 ## [1.3.15] - 2026-07-30