ecoportal-api-graphql 1.3.16 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2eada698a590c0214f8eb7a37255efe68c2573de6c73e3e1ce42ba6a8ff5accb
-  data.tar.gz: 316b65e4027224711711d2248ada651911b1e64ce48aeff6bffb22144e53cd11
+  metadata.gz: e679d934d9305d1926abe7251617eea0e5333c04665672b25f5ad38afb67d9b3
+  data.tar.gz: 2b8047d56b9af371b71308bcabce23f8e4c4b67d014ce7a4095386fadb1f89f4
 SHA512:
-  metadata.gz: f0894ce98e42628e50bb594ccbaa0050ae07518517a08745d54f5f61dc4031f959163b69caa1768ed978d0499abbb478c2dc4811867239373c324cac8008cc2a
-  data.tar.gz: 43e3dcf9dd61f521573a2249d26c92a571c23f06f2c742e9b19aa5554832b1195b251f0832da70f6231c68c0f94e108ff6487738a1e81e1c8c7d214944a98e0d
+  metadata.gz: 6ec6f2792de809534943497a98a74ec012b061778d379bb9f8ac205805cd9a629386c3293ee00e647549564fed5edbbc80e73cf856340922548309b8e9c68435
+  data.tar.gz: 948f0064aa886e310fc24f78a3919cbccc3b192495c724d86d003e1ff03bd39d2d12b312e82c04ca6626779abd822f9f9914de44b651c4903ba51d275085f7e8

data/CHANGELOG.md

@@ -2,15 +2,393 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.3.16] - 2026-08-13
+## [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.
+
+### 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).
+
+### 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 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 (`.ai-assistance/` 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
 

data/lib/ecoportal/api/common/graphql/model/diffable/leaf_diff_service.rb

@@ -0,0 +1,97 @@
+module Ecoportal::API::Common::GraphQL::Model::Diffable
+  # Diff strategy for models whose *array* attributes are leaf DATA, not nested
+  # `GraphQL::Model` children.
+  #
+  # Array attributes declared with `passarray` (tag lists, id lists, config lists)
+  # — and `embeds_many` id-collections written as a whole set (e.g. page `locations`)
+  # — are registered as *cascaded* attributes. The default `DiffService`:
+  #   1. strips cascaded keys from the flat classic diff
+  #      (`doc_with_non_cascaded_attributes`), on the assumption that a later
+  #      `diff_reduce` pass re-adds them by cascading into nested `GraphQL::Model`
+  #      children; and
+  #   2. in `diff_reduce`, deletes the flat placeholder for every cascaded key and
+  #      only re-adds it when the child object `is_a?(GraphQL::Model)`.
+  # A `passarray` is wrapped as a v2 `ArrayModel` and a whole-set `embeds_many` as a
+  # `CollectionModel` — neither is a `GraphQL::Model`, so the re-add never happens and
+  # the array change becomes **invisible to `as_update`** (scalar `passthrough` fields
+  # are unaffected). This is the systemic "array/leaf fields don't diff" root cause
+  # (see `.ai-assistance/code/model_input_mapping/SYNTHESIS.md` §3.1).
+  #
+  # This service fixes it for leaf models by:
+  #   1. keeping cascaded keys in the flat classic diff (`doc_with_non_cascaded_attributes`
+  #      is a no-op), and
+  #   2. overriding `diff_reduce` so the flat-diff placeholder for a NON-model leaf
+  #      child is preserved (only real `GraphQL::Model` children are cascade-diffed;
+  #      `root!` children are still dropped as independent entities), and
+  #   3. treating a leaf array as an OPAQUE value: a change replaces the whole array
+  #      (a full-set replace), rather than the id-keyed nested update/delete/create
+  #      patch-ops the default array diff would emit. This matches how the write inputs
+  #      consume these arrays (`PageInput.otherTags`, `PageInput.locations = [{ id: }]`,
+  #      register `filterTags`, PresetView `fieldConfigurations`).
+  #
+  # A model can either behave as a full leaf (call `dirty?`/`as_update` with
+  # `flat: true`, as `Base::Page::DataField` does — it has no nested `GraphQL::Model`
+  # children at all) or as a mixed model with both leaf arrays and real nested model
+  # children (page / register / preset view — the default cascaded `as_update` still
+  # recurses into the model children while the leaf arrays now diff inline).
+  class LeafDiffService < DiffService
+    private
+
+    # Keep all doc keys: leaf-field arrays are data, not nested models, so the flat
+    # classic diff must see them (the default strips every cascaded key).
+    def doc_with_non_cascaded_attributes(json)
+      json
+    end
+
+    # Treat array values as opaque leaves: emit the whole (current) array on any
+    # change, instead of the default id-keyed nested-array patch-ops. Non-array
+    # values fall through to the standard diff.
+    def change_diff(curr, prev, ignore: [])
+      return super unless curr.is_a?(Array) || prev.is_a?(Array)
+      return NO_CHANGES if same_array?(curr, prev)
+
+      keys_to_sym_deep(curr)
+    end
+
+    # Full-set equality (order-insensitive), mirroring `patch_data_flat_array`.
+    def same_array?(curr, prev)
+      curr ||= []
+      prev ||= []
+      curr.length == prev.length && (curr & prev).length == prev.length
+    end
+
+    # Preserve the flat-diff placeholder for non-model leaf children; only
+    # cascade-diff real `GraphQL::Model` children, and still drop `root!` children.
+    def diff_reduce(init, ignore: [])
+      subject.cascaded_reduce(init, recurs: false) do |result, obj, _key, key_path, _trace|
+        next result if key_path.empty?
+        next result if obj == subject
+
+        sym_path = key_path.map(&:to_sym)
+
+        unless cascadeable_model?(obj)
+          # Leaf array (ArrayModel / CollectionModel) → keep the flat-diff value.
+          # A root! child is not mutation payload → drop its placeholder.
+          dig_delete!(result, sym_path) if root?(obj) && result && dig_path?(result, sym_path)
+          next result
+        end
+
+        # Remove the flat-diff placeholder before the child computes its own diff.
+        dig_delete!(result, sym_path) if result && dig_path?(result, sym_path)
+
+        value = obj.as_update(ignore: ignore)
+        next result if value.nil?
+
+        result      ||= {}
+        result[:id] ||= get_id(keys_to_sym_deep(curr_doc(flat: true) || {}), exception: false)
+        dig_set!(result, sym_path, value)
+        result
+      end
+    end
+
+    # A child worth cascading into: a non-root GraphQL::Model.
+    def cascadeable_model?(obj)
+      obj.is_a?(Ecoportal::API::Common::GraphQL::Model) && !root?(obj)
+    end
+  end
+end

data/lib/ecoportal/api/common/graphql/model/diffable.rb

@@ -7,6 +7,7 @@ module Ecoportal
             require_relative 'diffable/hash_diff_nesting'
             require_relative 'diffable/classic_diff_service'
             require_relative 'diffable/diff_service'
+            require_relative 'diffable/leaf_diff_service'
 
             DIFF_CLASS = DiffService
 

data/lib/ecoportal/api/graphql/base/action.rb

@@ -29,7 +29,7 @@ module Ecoportal
           embeds_one :createdAt, klass: Base::DateTime
           embeds_one :updatedAt, klass: Base::DateTime
           embeds_one :completedAt, klass: Base::DateTime
-          embeds_one :openededAt, klass: Base::DateTime
+          embeds_one :openedAt, klass: Base::DateTime
           embeds_one :closedAt, klass: Base::DateTime
           embeds_one :dueOrClosedDate, klass: Base::DateTime
 

data/lib/ecoportal/api/graphql/base/action_event.rb

@@ -0,0 +1,23 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # A scheduled/recurring occurrence of an action (calendar-style event view).
+        # Read-only. `occursAt` is an ISO8601 timestamp scalar (a plain string),
+        # not the `{ dateTime:, timeZone: }` DateTime object used elsewhere.
+        #
+        # status is exposed as a plain string ('open' | 'closed').
+        class ActionEvent < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :uid
+          passthrough :title, :subtitle, :description
+          passthrough :status, :relativeStatus
+          passthrough :occursAt
+          passboolean :archived, :recurring, :standaloneAction
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/action_event_page.rb

@@ -0,0 +1,16 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # The page (and stages) an ActionEvent is attached to. Read-only.
+        class ActionEventPage < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :name, :fieldId
+          passarray :stageIds
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/activity.rb

@@ -0,0 +1,38 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # A single entry of a page's activity/history feed, returned by
+        # `page.activities` (ActivityInterfaceConnection). Read-only.
+        #
+        # `ActivityInterface` is an INTERFACE with ~61 concrete implementations
+        # (ActivityPageChangelog, ActivityComment, ActivityStageAssigned,
+        # ActivityCreated, ActivityEmailOut, ActivityFallback, ...). Rather than
+        # hand-model all of them, this captures the fields COMMON to the interface
+        # and passes the concrete `__typename` through so callers can branch on it.
+        #
+        # Enum-valued fields are exposed as plain strings:
+        # - priority: PriorityEnum
+        class Activity < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          # Concrete type name (e.g. 'ActivityPageChangelog', 'ActivityComment', 'ActivityFallback').
+          passthrough :__typename
+          passthrough :priority
+          passthrough :stageId
+          passthrough :timeZone
+          # Origin of the activity — sourceId/sourceName are scalars; the polymorphic
+          # `source: SourceUnion` (BasicPage|PhasedPage) subtree is intentionally omitted.
+          passthrough :sourceId, :sourceName
+          passthrough :userId, :userEmail, :userName
+          passarray :categories, :subkey
+          passboolean :system, :fromPublicTemplate
+
+          embeds_one :createdAt, klass: Base::DateTime
+          embeds_one :updatedAt, klass: Base::DateTime
+        end
+      end
+    end
+  end
+end