ecoportal-api-graphql 1.3.17 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8ab1262f84b1fada9c29cfcaa29ec70f38aa6e8d05762b3bb580ece22910eec
-  data.tar.gz: 25240f9c150f55a10a55284e647b42c3d96426fedafdc2ac866ada347e3a1794
+  metadata.gz: e679d934d9305d1926abe7251617eea0e5333c04665672b25f5ad38afb67d9b3
+  data.tar.gz: 2b8047d56b9af371b71308bcabce23f8e4c4b67d014ce7a4095386fadb1f89f4
 SHA512:
-  metadata.gz: 89e3340050db60aa9114b595b6d63f7e0d1bfc9aa3c36c273c14fb680ce78573318440a25c35c79b5d8413e668b275837d509572b3c93fceed965458056d6f43
-  data.tar.gz: bd9641bd8aad69ee8e1db51cda0c59ee46225c913f0fa19ee1ed2834f6ebd58493eb26b77b0ca1170abef1d058ae613f0c4ebb0541adb0f677169def9eeb3a7f
+  metadata.gz: 6ec6f2792de809534943497a98a74ec012b061778d379bb9f8ac205805cd9a629386c3293ee00e647549564fed5edbbc80e73cf856340922548309b8e9c68435
+  data.tar.gz: 948f0064aa886e310fc24f78a3919cbccc3b192495c724d86d003e1ff03bd39d2d12b312e82c04ca6626779abd822f9f9914de44b651c4903ba51d275085f7e8

data/CHANGELOG.md

@@ -2,24 +2,393 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.3.17] - 2026-09-30
+## [Unreleased]
+
+## [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`, `integration-training`, `multi_org_api` and
+`multi-org-idle` 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-assistance/`
+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.
 
-### Security
+### 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 `.ai-assistance/code/ecoPortal_architecture/02_data_model.md`.
+- **`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 `.ai-assistance/projects/data-toolset/` — 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).
 
-- 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).
+### Changed
 
-## [1.3.16] - 2026-08-13
+- `ecoportal-api` dependency floor raised to `0.10.17`: inherits the `WithRetry` fix that
+  makes `HTTP::TimeoutError` (connect/read/write timeouts) retryable — previously a single
+  transient timeout killed whole batch loops (live-confirmed on Farmers, 2026-07-30).
+- **`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
+  (act-gov TOOCS 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 / multi_org_api /
+  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%.
+- `.ai-assistance/projects/mns-template-lifecycle/WORKBOOK-FIELD-MAPPING.md` — the authoritative
+  workbook-to-template contract recovered verbatim from the 2026-08-08 session transcript:
+  `QuestionSetReference` → template_container_id (UI "UNIQUE IDENTIFIER"), `QuestionReference` →
+  field `description` (CONFIRMED), `QuestionInformation` → field tooltip (strip HTML entities),
+  scores ignored, section-vs-stage left ambiguous, plus the template-pairing procedure and the
+  DEV-site targeting note.
+- `.ai-assistance/conventions/recovering-prior-context.md` — past sessions are greppable JSONL
+  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
 
@@ -145,7 +514,7 @@ signed-off future decision.)
     (`external_id`/`id`/`state`) — a spurious path produced term `membranes.external_id.external_id`
     → 0 results (silent miss → dup-on-upsert). Register FIELD keys still get the nested path.
   - Verified against the backend filter definitions; catalogued in
-    the repo's internal docs.
+    `.ai-assistance/code/filter_contract_matrix.md`.
 
 ### Added
 
@@ -217,7 +586,7 @@ shapes checked against the live schema dump); the live UAT→PROD round trip is
   longer exists (fragments are a registry now) → `uninitialized constant … Fragment::… (NameError)` at
   render time. Now `spread :Action` / `spread :ContractorEntity`, matching the already-migrated queries.
   (The sibling breakage in eco-helpers' location-command optimizations is fixed in eco-helpers 3.2.17;
-  it crashed a customer's live locations sync.)
+  it crashed the live act-gov locations sync.)
 - **Kickstand workflow mutations — bare `DateTime` selection.** `Kickstand::{Start,Stop,Fail}Workflow`
   selected `startedAt`/`stoppedAt`/`failedAt` bare → "Field must have selections". Now
   `{ dateTime timeZone }` (same class as the 1.3.10 LocationStructure fix).
@@ -245,7 +614,7 @@ shapes checked against the live schema dump); the live UAT→PROD round trip is
 
 ## [1.3.10] - 2026-07-03
 
-Hotfix (backwards-compatible). Resolves a live failure on a customer's users sync.
+Hotfix (backwards-compatible). Resolves a live failure on the Turners & Growers users sync.
 
 ### Fixed
 

data/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2022 ecoPortal
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2022 ecoPortal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,24 +1,24 @@
-# Ecoportal::API::GraphQL
-
-This is a basic collection of helpers that can be used to interact with the
-[ecoPortal](https://www.ecoportal.com) `GraphQL` API
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'ecoportal-api-graphql', require: %w[ecoportal/api-graphql]
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install ecoportal-api-graphql
-
-## Changelog
-
-See {file:CHANGELOG.md} for a list of changes.
+# Ecoportal::API::GraphQL
+
+This is a basic collection of helpers that can be used to interact with the
+[ecoPortal](https://www.ecoportal.com) `GraphQL` API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ecoportal-api-graphql', require: %w[ecoportal/api-graphql]
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ecoportal-api-graphql
+
+## Changelog
+
+See {file:CHANGELOG.md} for a list of changes.

data/lib/ecoportal/api/common/graphql/CLAUDE.md

@@ -0,0 +1,36 @@
+# common/graphql
+
+Shared HTTP transport, authentication, and base model infrastructure used by the gem — nothing here is EcoPortal-domain-specific.
+
+## Contents
+
+| File / class | Purpose |
+|---|---|
+| `auth_service.rb` / `AuthService` | OAuth2 password + refresh-token flow; included in both client classes |
+| `client.rb` / `Client` | Graphlient-based GraphQL client (builds bearer-token headers, constructs endpoint URL) |
+| `http_client.rb` / `HttpClient` | Raw HTTP client (extends `Common::Client`); `execute` sends query strings + variables; supports v0–v3 + graphql API version modes |
+| `class_helpers.rb` / `ClassHelpers` | `becomes(klass)` instance casting + `const?` class helper |
+| `hash_helpers.rb` / `HashHelpers` | Deep key transforms (`keys_to_sym_deep`, `deep_dup`, `remove_nil_keys_deep`) — used by diff and input serialisation |
+| `query_integration.rb` / `QueryIntegration` | Class macro `query(:method, query_klass:)` that wires a named query method on `Model::Organization` |
+| `model.rb` / `Model` | Base model class: `DoubleModel` + `Diffable` + `AsInput`; all GraphQL models ultimately inherit this |
+| `patches.rb` | Reserved placeholder (empty) |
+| `model/diffable.rb` | `as_update` / `dirty?` — delegates to `DiffService` |
+| `model/as_input.rb` | `as_input` (instance) and `as_input(hash)` (class method) — converts diff to GraphQL mutation variables |
+| `model/diffable/diff_service.rb` | Main diff engine: flat classic diff + cascaded reduce through nested `GraphQL::Model` objects |
+| `model/diffable/classic_diff_service.rb` | Low-level change-data extraction (compares `curr_doc` vs `prev_doc`) |
+| `model/diffable/hash_diff.rb` | Hash equality / change detection helpers |
+| `model/diffable/hash_diff_nesting.rb` | Nested key path helpers (`dig_set!`, `dig_delete!`, `dig_path?`) |
+
+## Conventions
+
+- `Client` is graphlient-based and used for schema introspection; `HttpClient` is the actual request sender used in production (set as `client.http_client`).
+- `HashHelpers` is used as both a module mixin (include) and directly via `HashHelpers.keys_to_sym_deep(...)`.
+- `DiffService` handles the `flat:` flag: `flat: true` does a single-level diff; `flat: false` (default) cascades through nested `GraphQL::Model` objects.
+- Root-class objects (`root!` declared) are excluded from cascaded diffs — they represent independent server entities.
+- `AsInput#as_input(target_class:)` delegates to `Input::X.from_model(self)` when a target class is given.
+
+## Related
+
+- `../graphql/logic/base_model.rb` — adds `SnakeCamelAccess` on top of `Common::GraphQL::Model`
+- `../graphql/logic/input.rb` — `Logic::Input` base class built on top of `Model`
+- `../graphql/logic/base_query.rb` — consumes `HttpClient#execute` and `HashHelpers`