ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/projects/ooze-graphql-native-migration/analysis/2026-07-01-forces-via-workflow-commands-miss-rca.md

@@ -1,148 +0,0 @@
-# RCA — "Forces are blocked on GraphQL" was wrong: forces are mutable via the Workflow* command-bus
-
-**Date:** 2026-07-01
-**Author:** retrospective analysis (AI agent), reviewed-by: pending (Oscar)
-**Scope:** Why a clarified platform fact — *forces are created/edited/removed on GraphQL via `Workflow*` command types through `executeWorkflowCommands`* — was repeatedly missed, leaving a stale "blocked on forces" narrative in `eco-helpers` that disabled ~50% of ooze cases.
-**Constraint:** analysis + recommendations only. No source code was changed.
-
----
-
-## 1. Executive summary
-
-**What was missed.** ecoPortal FORCES are fully mutable on GraphQL through the `WorkflowCommandInput` command-bus — `addForce` / `editForce` / `removeForce` / `reorderForces` / `addBinding` / `editBinding` / `removeBinding` — applied via the `executeWorkflowCommands` mutation. The gem has shipped these command inputs **and** the mutation client since 2026-06-10/11. There is **no** separate "forces endpoint" and there never needed to be one for *writes*.
-
-**The one-line root cause.** The `OozeRedirect.force_support?` readiness gate keyed on the wrong signal — the presence of a **broken READ query** (`Query::PageWithForces`) — and when that signal flipped true it routed *every* ooze case through the broken read. The fix was to hard-disable the gate (`force_support? => false`), which threw out the **working MUTATE path** as collateral and froze a comment that over-generalises "the broken read" into "forces are NOT usable on GraphQL." The READ-vs-MUTATE distinction was never made explicit at the gate, so a read-only defect masqueraded as a total-capability block.
-
-**Net effect.** `ooze_redirect.rb` simultaneously (a) ships a `ForceCompat` that *correctly* drives writes through `executeWorkflowCommands`, and (b) asserts in prose that "Forces are NOT usable on GraphQL yet … blocked on GraphQL endpoint," listing ~50% of ooze cases as blocked. The codebase contradicts itself.
-
----
-
-## 2. The contradiction, with file:line evidence
-
-### Side A — "forces are blocked" (eco-helpers)
-
-`C:\ruby_scripts\git\eco-helpers\lib\eco\api\usecases\graphql\compat\ooze_redirect.rb`
-
-- **L42-49** — `## Limitations`: "Force / binding operations (`target.forces`, `force.bindings`) are not available in GraphQL — those calls will raise NoMethodError."
-- **L51-77** — `## TODO: Force / binding support (blocked on GraphQL endpoint)`: "Engineering is working on exposing 'legacy forces' via the GraphQL API. Once that endpoint is available, extend this module with a `ForceCompat` sub-module …" — followed by a v2-shaped API sketch (`target.forces.get_by_name`, `force.bindings.add`, `force.custom_script = new_script`) and a roster of ~22 named cases across 10 orgs declared "currently blocked … ~50% of all ooze cases."
-- **L113-122** — `force_support?`:
-  ```ruby
-  # Forces are NOT usable on GraphQL yet: Query::PageWithForces is a WIP whose query
-  # currently fails schema validation … and the backend forces endpoint is still in
-  # progress. … Keep OFF until forces actually work …
-  def self.force_support?
-    false
-  end
-  ```
-
-### Side B — "forces are mutable, right now" (the gem, already shipping)
-
-- `lib\ecoportal\api\graphql\input\workflow_command.rb` **L106-117** — the `# Forces` block of `COMMAND_MAP` wires `addForce`, `removeForce`, `editForce`, `reorderForces`, `addBinding`, `editBinding`, `removeBinding` (+ `addLinkedHelper`/`editLinkedHelper`/`removeLinkedHelper`). These are first-class members of the command-bus, on the same footing as `addStage`, `addField`, etc.
-- `lib\ecoportal\api\graphql\input\workflow_command\add_force.rb` — `VALID_KEYS = %i[placeholderId name customScript url contentB64]`, `SCHEMA_VERSION '20260605'`.
-- `…\edit_force.rb` — `VALID_KEYS = %i[id name customScript url contentB64]`.
-- `…\add_binding.rb` — `VALID_KEYS = %i[placeholderId forceId name referenceId type]`.
-- `lib\ecoportal\api\graphql\mutation\page\execute_workflow_commands.rb` — `field_name :executeWorkflowCommands`; the generic command applier (`mutation(... commands: :WorkflowCommandInput!)`).
-- `lib\ecoportal\api\graphql\mutation\page\execute_force_commands.rb` **L26-37** — `ExecuteForceCommands` is now a thin `@deprecated` alias that *delegates to the same `executeWorkflowCommands` mutation*. Its own doc-comment (L20-25) shows `{ editForce: {...} }`, `{ addBinding: {...} }`, `{ removeBinding: {...} }`, `{ removeForce: {...} }` as the command payloads.
-- `lib\ecoportal\api\graphql\base\force.rb` **L33-60** — `Base::Force#custom_script=` queues `editForce`; `#all_pending_commands` emits `{ editForce: { id:, customScript: } }`; bindings queue `addBinding`/`removeBinding`. The write model is complete and unit-shaped.
-
-### Side C — the smoking gun: the "v2-style" sketch is already the command-bus
-
-The "to be built when the endpoint lands" sketch in `ooze_redirect.rb` (L79-89) describes exactly what the **already-shipped** `force_compat.rb` does — and that file does **not** call any forces endpoint:
-
-`C:\ruby_scripts\git\eco-helpers\lib\eco\api\usecases\graphql\compat\ooze_redirect\force_compat.rb`
-- **L43-46, L62-66** — `process_ooze` → `save_force_changes!` → `graphql.page.execute_force_commands(id:, patch_ver:, commands:)`, i.e. it submits `force_col.pending_commands` **through `executeWorkflowCommands`**. The write half was *finished* the same day the TODO was written.
-
-So the prose ("blocked on endpoint," "to be built") and the code ("here is the working write path through the command-bus") are in direct contradiction *within the same module*.
-
----
-
-## 3. The read-vs-mutate conflation (the conceptual core)
-
-Two genuinely distinct concerns were collapsed into one boolean:
-
-| Concern | Mechanism | Status (as of 2026-06-30) |
-|---|---|---|
-| **(a) READ legacy forces on a page** | `Query::PageWithForces` — selects `forces { ...ForceFields }` on the page union | **WIP / broken**: per commit `de62d2d1`, the query "fails schema validation (PageUnion selections; `id` on DataFieldBinding/SectionBinding; unused ForceFields)." This is a *client query shape* defect. |
-| **(b) MUTATE forces** | `executeWorkflowCommands(commands: [WorkflowCommandInput])` with `editForce`/`addBinding`/`removeForce`/… | **Working / shipped** since 2026-06-10 (`cd57b54`) and folded into the unified command-bus 2026-06-11 (`8e8f492`). |
-
-The v2 mental model treats a force as a *page sub-object you read, then mutate in place*: `page.forces.get_by_name(...)`, `force.bindings.add(...)`, `force.custom_script = ...`, with a LISP `custom_script` you edit. In that model, reading and writing are the **same** object graph, so "I can't read forces" naturally implies "I can't do forces."
-
-The new platform model is **imperative**: you don't read-then-mutate a live object; you *emit commands* (`editForce { id, customScript }`, `addBinding { forceId, ... }`) into `executeWorkflowCommands`, exactly like every other template/workflow change. In this model, **read and write are decoupled** — a write needs only the force/binding `id` and the new value; it does **not** require `PageWithForces` to be schema-valid.
-
-**The conflation:** because the gate (`force_support?`) was attached to the *read* query, and because `force_compat.rb` *also* uses `PageWithForces` to fetch (`with_each_entry`, L30-40), the broken read poisoned the whole feature. The "blocked" conclusion was drawn from the broken READ query and then **over-generalised to ALL force operations** — including the writes that already worked. The v2 carryover (looking for a forces *endpoint*, i.e. a place to read forces from) is precisely what made the read query feel like the readiness signal.
-
----
-
-## 4. Git timeline — what existed when
-
-**Gem (`ecoportal-api-graphql`):**
-
-| Date | Commit | Event |
-|---|---|---|
-| 2026-06-10 | `cd57b54` | `feat: Force model + fragment + mutation + query for ForceCompat support` — adds `Base::Force` (+ bindings, collection, `custom_script=` queues `editForce`), `Fragment::ForceFields`, **`Mutation::Page::ExecuteForceCommands` (write)** AND **`Query::PageWithForces` (read)** together. Writes were present from day one. |
-| 2026-06-11 | `8e8f492` | `feat: expose PagesWorkflow space (W1-W5) — read models, command bus, fragments, specs, docs` — adds the full `WorkflowCommand` command-bus incl. `add_force/edit_force/remove_force/reorder_forces/add_binding/edit_binding/remove_binding`; `ExecuteForceCommands` becomes a deprecated delegator to `executeWorkflowCommands`. |
-| 2026-06-16 | `bafbf80` | `fix: require all field_config byType modules in WorkflowCommand`. |
-
-**eco-helpers (`ooze_redirect.rb` / `force_compat.rb`):**
-
-| Date | Commit | Event |
-|---|---|---|
-| 2026-06-09 | `457eccd9` | `feat: GraphQL::Compat::OozeRedirect` — shim created. |
-| 2026-06-09 | `244aff8a` | `docs: OozeRedirect Forces TODO block` — **the "blocked on GraphQL endpoint" prose written BEFORE the write path shipped.** At this moment the claim was *defensible*. |
-| 2026-06-10 | `e3bc7f0a` | `feat: OozeRedirect::ForceCompat — force/binding support via GraphQL` — the working write path lands (`save_force_changes!` → `execute_force_commands`). **The TODO prose was now stale but was not removed.** |
-| 2026-06-30 | `de62d2d1` | `fix(ooze-redirect): disable ForceCompat (forces WIP)` — `force_support?` was `defined?(Query::PageWithForces)`; once the gem force-loaded that became `true`, prepending `ForceCompat` for *every* case and routing `with_each_entry` through the broken read. Hard-disabled to `false`. **This correctly stopped the broken read from breaking toocs/cans — but the accompanying comment re-asserted the over-general "forces are NOT usable" claim, re-freezing the stale narrative instead of narrowing it to the read query.** |
-| 2026-06-30 | `d12f5552` | `fix(ooze-redirect): faithful dry-run + slim shim` — current state. |
-
-**Key finding:** the write command inputs existed (2026-06-10/11) *before* the "blocked" claim was last reinforced (2026-06-30). The reinforcement on 2026-06-30 had the gem's working force-write code sitting in the same dependency tree — yet the comment still said "blocked on GraphQL endpoint." The DECISIONS log entry of the **same day** (`[2026-06-30] Forces-dependent cases are HELD pending a Phase 0 live readiness test`, `ooze-graphql-native-migration/DECISIONS.md` L120-148) *did* finally record the correction ("the GraphQL force endpoint is NOT read-only or missing — the gem ships both … read AND … write"). So the correction landed in the **project decision log** but did **not** propagate back into the `ooze_redirect.rb` gate/comment that consumers and future agents actually read.
-
----
-
-## 5. Root-cause chain (ranked)
-
-1. **Wrong readiness signal + read/write coupling (primary).** `force_support?` keyed on `defined?(Query::PageWithForces)` — a *read* class — as a proxy for "forces work." Because `force_compat.rb#with_each_entry` *fetches* via `PageWithForces`, the broken read could break unrelated cases, forcing a binary all-off switch. A capability that is two independent halves (read vs write) was gated by one boolean tied to the broken half. The write half was never given its own gate, so it died with the read.
-
-2. **Stale doc never re-examined after the feature shipped (close second).** The "blocked on endpoint" TODO was written 2026-06-09 (`244aff8a`) when it was *true*, then the write path shipped 2026-06-10 (`e3bc7f0a`) **in the same module**, and the TODO was never reconciled. Doc rot: the prose became a fossil that subsequent edits (incl. 2026-06-30) treated as ground truth and even *expanded* rather than questioned.
-
-3. **Verified platform fact lived only in machine-local memory, invisible across sessions/agents (structural).** The general command-bus architecture ("templates updated imperatively via ~80 `WorkflowCommandInput` types") was captured in `project_template_update_architecture.md` and `project_workflow_space.md` under `C:\Users\rella\.claude\projects\…\memory\` — a **per-machine, gitignored** store. That store is invisible to (a) other machines, (b) other agents/sessions, (c) anyone reading the repo. The fact was "known" in one silo but had no **code-adjacent, shared** form, so it could not contradict the stale comment at the point of use.
-
-4. **The captured general fact was never specialised to the force inference (reasoning gap).** Even where the command-bus was known, nobody made the *specific* deduction: "forces are members of the command-bus → forces are mutable on GraphQL → `force_support?` must not be hard-false for writes." The general → specific link was never drawn. Knowing "templates are updated via commands" did not automatically surface "therefore the forces-blocked claim is wrong," because forces were mentally filed under "legacy read object," not "command-bus member."
-
-5. **v2 endpoint mental model (contributing).** The team looked for a forces *endpoint* (a place to read/CRUD forces as objects) rather than recognising forces as just-another-command in an existing imperative bus. This is why the read query felt load-bearing and why the TODO sketch reinvented a v2-shaped `forces.get_by_name/.bindings.add` API that the command-bus had already obviated for writes.
-
----
-
-## 6. Concrete corrections
-
-### (a) `ooze_redirect.rb` — gate + comment (DESCRIBE; not applied)
-
-- **Split the capability into READ vs WRITE.** Do not let a single `force_support?` boolean conflate them.
-  - **Writes** (`editForce`/`addBinding`/`removeBinding`/`removeForce` via `executeWorkflowCommands`) are available **now** and do not depend on `PageWithForces`. The write path in `force_compat.rb#save_force_changes!` is correct as written.
-  - **Reads** (`Query::PageWithForces`) are the only WIP part. The blocker is a *client query-shape* bug (PageUnion selection set; `id` on `DataFieldBinding`/`SectionBinding`; unused `ForceFields`), not a missing backend endpoint.
-- **Re-scope the gate.** Replace the hard `false` with a gate that reflects the real dependency: ForceCompat's *fetch* (`with_each_entry` via `PageWithForces`) is what must be gated, not force mutation per se. Options:
-  - Gate ForceCompat activation on a **read-readiness** check (only prepend `ForceCompat::Infrastructure` when `PageWithForces` is schema-valid against the live org), so toocs/cans never route through the broken read; **or**
-  - Decouple the fetch from the mutate: let ForceCompat reuse the *standard* page fetch and only add the write-command accumulation, fetching forces via a separate call (or a fixed `PageWithForces`) only for cases that actually touch forces. This lets writes proceed even while the read query is being fixed.
-- **Rewrite the prose (L42-89, L113-122).** Delete "Force / binding operations are not available in GraphQL" and "blocked on GraphQL endpoint." Replace with the accurate split: "Force/binding **writes** are available now via `executeWorkflowCommands` (`editForce`/`addBinding`/`removeBinding`/`removeForce`). The only WIP is **reading** existing forces on a page (`Query::PageWithForces` fails schema validation — fix the selection set). The ~50% 'blocked' roster is **not** blocked on a missing endpoint; it is at most blocked on the read query for cases that must *inspect* current forces before mutating." Keep the case roster but relabel it "force-touching cases (verify read-vs-write need per case)."
-- **Cross-link** the comment to the DECISIONS entry (`ooze-graphql-native-migration/DECISIONS.md` L120-148) so the gate and the decision log can't drift apart again.
-
-### (b) verified-platform-knowledge entry to capture
-
-Create a durable, **repo-committed** platform-fact entry (not machine-local memory):
-
-> **Forces on GraphQL are mutated via the `WorkflowCommandInput` command-bus, applied with the `executeWorkflowCommands` mutation.** Command keys: `addForce`, `editForce`, `removeForce`, `reorderForces`, `addBinding`, `editBinding`, `removeBinding` (gem: `Input::WorkflowCommand::*`, `COMMAND_MAP` L106-117). There is **no** separate forces write endpoint. A force `editForce` needs only `{ id, customScript }`; a binding needs `{ forceId, name, referenceId, type }`. Confirmed by Oscar (more than once) and by shipped gem code (`cd57b54` 2026-06-10, `8e8f492` 2026-06-11).
-> **Only WIP part:** *reading* existing forces on a page via `Query::PageWithForces` — currently fails client-side schema validation (PageUnion selection set; `id` on `DataFieldBinding`/`SectionBinding`). This is a query-shape fix, not a backend gap.
-> **Anti-pattern to retire:** the v2 "forces endpoint / `page.forces` live object" mental model. Forces are command-bus members, not a CRUD endpoint.
-
-Suggested home: a committed `verified-platform-knowledge` doc (e.g. under `.ai-assistance/code/` or a `.ai-assistance/local/standards-requests/` entry that gets promoted to a shared, committed location — note: `.ai-assistance/local/standards-requests/` does **not currently exist** in this repo, see §7).
-
-### (c) process fix to prevent recurrence
-
-1. **Promote verified platform facts out of machine-local memory into committed, code-adjacent docs.** The command-bus fact lived only in `~/.claude/.../memory/` (gitignored, per-machine). A platform fact that gates real code MUST be captured where every agent/session/teammate and the code reviewer can see it — i.e. committed to the repo near the code it governs. This is the textbook case the `verified-platform-knowledge` standards request is meant to solve: a user-clarified fact that never became durable shared knowledge, so a stale "blocked" assertion survived and was reinforced.
-2. **Doc-and-gate co-location invariant.** When a feature ships its write path (commit `e3bc7f0a`), any "TODO/blocked" prose describing that feature in the *same module* must be reconciled in the same change. A lint/check or a PR-checklist item: "Did this commit make any nearby 'blocked/TODO/not available' comment stale?"
-3. **Never gate a multi-part capability on a single boolean tied to one part.** Capability gates should name the *specific* dependency (here: "ForceCompat fetch needs a schema-valid `PageWithForces`"), not a coarse "forces work." A gate comment should be falsifiable and cite the exact failing artifact.
-4. **Close the loop from DECISIONS log back to code.** The 2026-06-30 DECISIONS entry recorded the correct fact but the `ooze_redirect.rb` gate/comment was not updated to match. Decision-log entries that contradict a code comment should spawn a tracked task to fix the comment, or the decision isn't "done."
-
----
-
-## 7. Note on the standards mechanism
-
-The task referenced `.ai-assistance/local/standards-requests/` (a `verified-platform-knowledge` request). **That directory does not exist in this repo as of 2026-07-01** (`.ai-assistance/local/` was not present). This RCA is therefore a concrete, documented justification for creating that mechanism: a verified platform fact (forces = `Workflow*` command-bus), clarified by the maintainer more than once, was never captured as durable, shared, **committed** knowledge — so a stale "blocked on endpoint" assertion persisted across three weeks and was actively reinforced even after the contradicting code shipped in the same module. A committed verified-platform-knowledge store, co-located with the gated code and cross-linked from the DECISIONS log, would have surfaced the contradiction at the gate.

data/.ai-assistance/projects/page-model/DECISIONS.md

@@ -1,245 +0,0 @@
-# Decisions — Page Model Project
-
----
-
-## 2026-06-07 — Two search modalities: org search vs register search
-
-**Context:** Scripts that need to find pages before updating them have two query paths,
-with fundamentally different data sources, performance profiles, and coverage.
-
-### Org search — `currentOrganization { pages(...) }`
-
-- **Source:** PostgreSQL DB, rendered by the API layer
-- **Returns:** `PageUnion` (`BasicPage | PhasedPage`) — the same model returned by
-  mutations, fully populated from the DB
-- **Performance:** Slow — approximately 3 seconds per page on render due to API-layer
-  data assembly. **Implication:** avoid re-fetching a page after update if possible;
-  the mutation payload already returns the updated `PageUnion`.
-- **Data completeness:** Full — includes `patchVer`, all field values, data field IDs
-  (server-assigned after DB creation), and the full type structure needed for mutations.
-- **Archived pages:** Supported via a query argument — can search archived pages.
-- **Best for:** Pre-update fetch (need `patchVer` + field IDs), post-build-from-template
-  fetch (need server-assigned field IDs to construct create input).
-
-### Register search — `currentOrganization { register(id:) { previewPages(...) } }`
-
-**Correction 2026-06-07 (verified from Insomnia production queries):** The field is
-`previewPages`, not `pages`. Archived pages ARE supported via `includeArchived: Boolean`
-parameter (defaults to `false`).
-
-- **Source:** Elasticsearch (ES) — the org's search index, not the DB
-- **Returns:** `PreviewPage` — field preview values from ES snapshots. No field IDs, no
-  `patchVer`, no typed data field models. Insufficient for building mutation inputs.
-- **Performance:** Fast — sub-second, ES-powered.
-- **Data completeness:** Partial — preview values only. Use to find page IDs, then switch
-  to org search for full data.
-- **Archived pages:** Supported via `includeArchived: Boolean` parameter.
-- **Extra args:** `presetViewId: ID` — applies a register PageView preset configuration.
-- **Best for:** Fast lookup by metadata (`externalId`, state, location tags, date ranges)
-  to get page IDs before switching to org search for full data fetch.
-
-### Search config — `SearchConf` (Hash type)
-
-The `searchConf` argument is not a typed GraphQL model — it is passed as a `Hash`
-(the schema shows it as `Search`). Engineering has backend classes for it but these are
-not exposed as GraphQL input types.
-
-**Verified structure (from Insomnia):**
-
-```json
-{
-  "filters": [ <filter_object>, ... ],
-  "sorters": { "key": "created_at", "direction": "asc" },
-  "query":   "optional full-text string"
-}
-```
-
-**Filter operations (snake_case strings):**
-- `exact_filter` — equality: `{ key: "external_id", value: "X" }`
-- `date_filter` — date range: `{ key: "updated_at", gte: "ISO8601", time_zone: "UTC" }`
-- `register_filter` — scope to registers (org search): `{ ids: ["id1"] }`
-- `and_filter` — explicit AND group: `{ filters: [...] }`
-- `or_filter` — OR group: `{ filters: [...] }`
-
-**Sorter:** `{ "key": "field_name", "direction": "asc"|"desc" }` — note key field is
-`key`, not `fieldName`. Can be a single object or an array.
-
-Full reference with all production examples: `.ai-assistance/code/search_filters.md`
-
-**Reference:** Search filter docs partially exist in Confluence APIDOCS (most common
-filters). Full coverage is pending — see the Search Filter Builder project.
-
----
-
-## 2026-06-07 — CommonPageUnion: unified fragment for all page integration patterns
-
-**Context:** Customer integration scripts share three fundamental page interaction patterns,
-all of which require reading the full page content (including data field IDs and structure):
-
-1. **Build from template** — After calling `buildFromTemplate`, the server returns a built
-   draft whose data field IDs are already assigned by the DB. Scripts must fetch this draft
-   via `CommonPageUnion` to retrieve those IDs before they can construct the `dataFields`
-   input for the subsequent `createFromTemplate` call.
-
-2. **Fetch before update** — Before calling `updatePage`, scripts must fetch the current page
-   via `CommonPageUnion` to get the current `patchVer` (required for optimistic concurrency)
-   AND the current data field IDs and values. Field IDs change after DB creation and cannot
-   be assumed — they must be read from the live page.
-
-3. **Fetch after create/update** — To confirm the result, scripts re-fetch via
-   `CommonPageUnion` and inspect the returned state.
-
-**Decision:** `Fragment::Pages::CommonPageUnion` is a single, parameterised fragment that
-covers all three patterns. Rather than having separate lightweight/heavyweight variants,
-three boolean query variables control how much is fetched in a given call:
-
-| Variable | Purpose | Use in pattern |
-|---|---|---|
-| `$content` | Include field values, stage completions, people, files | (2) update, (3) verify |
-| `$only_content` | Exclude structural/config fields — content values only | (3) verify result |
-| `$fields` | Include data field definitions (labels, options, structure) | (1) build, (2) update |
-
-**Design rationale — educating customer technicians:** The two-step sequences for create
-and update were deliberately consolidated under one fragment to give customer technicians
-a clear, documented path into the GraphQL integration:
-
-- **CREATE sequence:** (a) `buildFromTemplate` → fetch built draft with `CommonPageUnion`
-  (`$fields: true`) to get data field IDs; (b) fill in values and call `createFromTemplate`.
-- **UPDATE sequence:** (a) fetch current page with `CommonPageUnion` (`$content: true,
-  $fields: true`) to get `patchVer` + current field IDs and values; (b) build update
-  operations and call `updatePage`.
-
-GraphQL's declarative nature (clients specify what they need) is new to many technicians.
-The directive variables make it visible and learnable — they can start with
-`$content: true, $fields: true` to get everything, then dial back once they understand
-what each variable controls.
-
-**Note on Build - Model (legacy pattern):** The Insomnia export contains an older
-`Build - Model` request with its own inline fragment definitions (no `CommonPageUnion`).
-This predates the unified fragment approach. It was used before the team settled on a
-single documented pattern for customer support knowledge sharing. Treat it as legacy;
-all new scripts should use the `Build - Standard` / `CommonPageUnion` approach.
-
-**Note on compound mutations:** The `ArchivePage` Insomnia request runs two mutations in
-one request — `updatePage` (blanks `externalId`) then `archivePage`. This is valid GraphQL
-(multiple operations in one definition, executed in declaration order by the server). It was
-designed for a customer whose middleware was stateless and could not sequence two separate HTTP
-requests within a session. The `operationName` field in the JSON payload identifies the
-primary named definition. This pattern is available to any integration that needs atomic
-sequencing without server-side transactions.
-
-**Reference:** Documented in Jira API Docs space (Confluence APIDOCS).
-Fragment lives at: `lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb`
-Accessed via: `fragment.pages.assemble(:CommonPageUnion)` or via `assemble_fragments`
-when `...CommonPageUnion` appears in a query string.
-
----
-
-## 2026-06-05 — Page model is phased; DataFields deferred to Phase E
-
-**Context:** Pages are the central EcoPortal entity with 50+ fields, two concrete types
-(BasicPage / PhasedPage), stages, sections, 20 data field types, AI features, and
-workflow. Attempting to implement everything at once is impractical.
-
-**Decision:** Phase the work. Phase A (read) and Phase B (write) cover the core lifecycle
-that customer scripts need. DataFields (Phase E) deferred — they require domain knowledge
-of field types and are unlikely to be needed for structural automation scripts.
-
-**Consequences:** Phase A/B output will not include `dataFields` in mutation inputs.
-Scripts that need to update field values must wait for Phase E.
-
----
-
-## 2026-06-05 — Page creation requires a template; no blank page mutation exists
-
-**Context:** The schema has no `createPage` mutation. All creation goes via
-`createPageFromTemplate(input: CreateFromTemplateInput!)` or `buildPageFromTemplate`.
-`CreateFromTemplateInput` takes `templateId: ID!` and optionally `dataFields`.
-
-**Decision:** Phase D (creation) is scoped to template-based creation only. No attempt to
-expose a blank-page creation API because none exists on the server.
-
-**Consequences:** Scripts that create pages must know the target template ID. The gem
-should provide a way to look up templates (`Query::Templates`).
-
----
-
-## 2026-06-05 — Both BasicPage and PhasedPage mapped; Stage deferred to Phase C
-
-**Context:** `PageUnion = BasicPage | PhasedPage`. PhasedPage adds stages; Stage has its
-own `dataFields`, `tasks`, `sections`. Scripting typically works at the Page level (not
-individual stage fields).
-
-**Decision:** Phase A maps `BasicPage` and `PhasedPage` as concrete model classes
-inheriting from `Interface::BasePage`. Stage model populated in Phase C. Scripts can
-access stages via `page.stages` once Phase C is done.
-
-**Consequences:** `PhasedPage#stages` returns raw data (passarray) until Phase C adds a
-proper `Stage` model class.
-
----
-
-## 2026-06-05 — `patchVer` always queried and always passed on update
-
-**Context:** `patchVer: Int!` is non-null on every page read. The `updatePage` mutation
-accepts it optionally. The server uses it for optimistic concurrency control.
-
-**Decision:** The Page fragment always includes `patchVer`. The `UpdatePage` mutation
-input always includes `patchVer` sourced from the model. This is not optional in our gem
-even though it is optional in the schema.
-
-**Reason:** Silent concurrency failures (last-write-wins without warning) are worse than
-an occasional stale-version rejection. Making `patchVer` mandatory in our usage prevents
-data loss from concurrent edits.
-
-**Consequences:** Any code that builds `UpdatePageInput` must have previously fetched the
-page to get the current `patchVer`. You cannot update a page you haven't read first.
-
----
-
-## 2026-06-05 — `stageId` in UpdatePageInput: Phase C concern
-
-**Context:** `UpdatePageInput` has `stageId: ID` which targets a specific stage on a
-phased page. Stage-specific operations (submit, review, complete) also use this.
-
-**Decision:** Phase B implements page-level updates only (name, state, locations, tags,
-`patchVer`). Stage-targeting (`stageId`, `submit`, `task` input) is Phase C.
-
----
-
-## 2026-06-06 — PageUnion implemented as a factory module, not a class
-
-**Context:** The GraphQL `page` and `pages` fields return `PageUnion = BasicPage | PhasedPage`.
-The response wrapping layer calls `response_class.new(data)` and connection node instantiation
-calls `node_class.new(item, parent: self)`. Both require a single "class" that can dispatch to
-the correct concrete type based on `__typename`.
-
-**Decision:** `Model::PageUnion` is implemented as a Ruby module with a custom `.new` method
-that inspects `doc['__typename']` and delegates to `Model::Page::Basic`, `Model::Page::Phased`,
-or `Interface::BasePage` (fallback). It is used as both `item_class` on `Query::Page` and
-`node_class` on `Connection::Page`.
-
-`class_resolver` accepts modules since `resolve_class` uses `Kernel.const_get` for strings and
-returns the constant as-is. The `.new` method passes through `**opts` so `parent:` and `key:`
-from `embeds_many` reach the concrete constructor correctly.
-
-**Consequences:** Callers always receive a concrete `Page::Basic` or `Page::Phased` instance —
-`PageUnion` itself is never instantiated. The `__typename` field must be included in the
-`PageFields` fragment for dispatch to work.
-
----
-
-## 2026-06-05 — Fragment::Page initial scope
-
-**Context:** `BasePageInterface` has 50 fields. Most are read-only context or authorization
-flags. Customer scripts primarily need identity, state, location, and versioning fields.
-
-**Decision (initial fragment scope):**
-- **Always include:** `id`, `name`, `uid`, `icon`, `patchVer`, `state`, `archived`,
-  `archivedAt`, `draft`, `externalId`, `timeZone`, `otherTags`, `taskPriority`,
-  `sourceTemplateId`, `createdAt`, `updatedAt`, `creatorName`
-- **Locations:** `locations { id name }` (via spread of `LocationNode` fragment)
-- **Exclude initially:** `dataFields`, `sections`, `workflow`, `forces`, `tasks`,
-  `comments`, AI fields, authorization `can*` fields
-
-Fields can be added to the fragment as needed by downstream scripts.

data/.ai-assistance/projects/page-model/TODO.md

@@ -1,190 +0,0 @@
-# TODOs — Page Model Project
-
-> Created 2026-06-05 from live schema introspection.
-> Natural implementation order: A → B → C → D → E
-> Phases C, D, E can be deferred — Phase A + B covers the core script use case.
-
----
-
-## Phase A — Read (queries, fragment, models)
-
-- [x] **A.1** Fragment::PageFields on BasePageInterface — all initial-scope fields + `...LocationNode`.
-  *Done 2026-06-07 — `lib/ecoportal/api/graphql/fragment/page.rb`*
-
-- [x] **A.2** Interface::BasePage: added `passboolean :draft`, `passthrough :externalId`.
-  *Done 2026-06-07 — archivedAt was already present*
-
-- [x] **A.3** `Base::Page::Basic < Interface::BasePage` (new); `Base::Page::Phased`: added `passarray :stages`.
-  *Done 2026-06-07 — naming follows existing nesting: Base::Page::Basic, Base::Page::Phased*
-
-- [x] **A.4** `Model::Page::Basic < Base::Page::Basic` (new); `Model::Page::Phased` already existed with resolvers.
-  *Done 2026-06-07*
-
-- [x] **A.5** `Query::Page` (single by id); `Model::PageUnion` factory dispatches on `__typename`.
-  *Done 2026-06-07 — PageUnion approach documented in DECISIONS.md*
-
-- [x] **A.6** `Query::Pages` — paginated, `Connection::Page` with `PageUnion` node_class.
-  *Done 2026-06-07*
-
-- [x] **A.7** `Model::Organization`: wired `query :page`, `query :pages`, `query :templates`.
-  *Done 2026-06-07*
-
-- [x] **A.8** `Query::Templates` — reuses `Connection::Page` and `PageFields` fragment.
-  *Done 2026-06-07*
-
-- [x] **A.9** RSpec specs for `Query::Page`, `Query::Pages`, fragment assembly.
-  `spec/ecoportal/api/graphql/query/page_spec.rb` — 7 examples (field_name, accepted_params,
-  item_class, PageFields/LocationNode/BasicPageFields/PhasedPageFields fragment assembly).
-  `spec/ecoportal/api/graphql/query/pages_spec.rb` — 7 examples (field_name, accepted_params,
-  item_class, connection_class, fragment assembly, SearchConf acceptance).
-  *Done 2026-06-07 — 14 examples, 0 failures*
-
----
-
-## Phase B — Write (update mutation)
-
-- [x] **B.1** `Input::Page` — `name/state/taskPriority/timeZone/externalId/locations/otherTags`.
-  *Done 2026-06-07 — `lib/ecoportal/api/graphql/input/page.rb`*
-
-- [x] **B.2** `Input::Page::Update.from_model` — nested `page:` sub-hash, always injects `patchVer`, supports `publish:` flag.
-  *Done 2026-06-07 — `lib/ecoportal/api/graphql/input/page/update.rb`*
-
-- [x] **B.3** `Mutation::Page::Update` + `Payload::Page::Update` (item via PageUnion).
-  *Done 2026-06-07*
-
-- [x] **B.4** `Mutation::Page::Archive` + `Mutation::Page::Unarchive` + corresponding payloads + inputs.
-  *Done 2026-06-07*
-
-- [x] **B.5** `Builder::Page`: `update/archive/unarchive` methods.
-  *Done 2026-06-07*
-
-- [x] **B.6** `Ecoportal::API::GraphQL#page` → `Builder::Page`.
-  *Done 2026-06-07*
-
-- [x] **B.7** RSpec specs: `Input::Page::Update.from_model` (no-change nil, patchVer, publish, clientMutationId); `Model::PageUnion` __typename dispatch.
-  *Done 2026-06-07 — archive/unarchive input specs deferred (low value, straightforward passthrough)*
-
----
-
-## Phase C — PhasedPage stages
-
-> Prerequisite: Phase A model classes exist.
-
-- [x] **C.1** Populate `Base::Page::Phased::Stage` with fields from `Stage` type:
-  `id`, `name`, `ordering`, `state`, `active`, `started`; predicate methods `active?`/`started?`;
-  `sections` → SectionCollection, `components` → DataField::Collection, `[]` hash-style access.
-  *Done 2026-06-07 — 17 specs in `spec/ecoportal/api/graphql/base/page/phased/stage_spec.rb`*
-
-- [x] **C.2** Add `embeds_many :stages, klass: Stage` on `Base::Page::Phased`.
-  *Done 2026-06-07 — `Compat::StageCollection#coerce_stage` wraps raw hashes in `Stage`*
-
-- [x] **C.3** Add `stageId` support to `Input::Page::Update` and `Mutation::Page::Update`
-  for stage-targeted updates.
-  *Done 2026-06-07 (commit 6305f69) — stageId + submit kwargs; non-nil result for stage-only submit*
-
-- [x] **C.4** Add submit/review task mutations: `approveReviewPageTask`, `rejectReviewPageTask`,
-  `batchUpdateReviewPageTask`, `restartReviewPageTask`, `undoReviewPageTask`.
-  `Input::Page::ReviewTask` (id, stageId, comment); `Payload::Page::ReviewTask` (item: PageUnion);
-  5 mutation classes; `Builder::Page` wired with `approve/reject/restart/undo/batch_update_review_task`.
-  *Done 2026-06-07 — 5 specs in `spec/ecoportal/api/graphql/input/page/review_task_spec.rb`*
-
----
-
-## Phase D — Creation from template
-
-- [x] **D.1** `Input::Page::CreateFromTemplate` — `templateId`, `showHiddenData`, `stageId`,
-  `submit`, `attach`, `draft`, `clientMutationId`, `dataFields` (raw passthrough), `page` (embeds_one).
-  *Pre-existing*
-
-- [x] **D.2** `Mutation::Page::CreateFromTemplate` — `createPageFromTemplate`, `CreateFromTemplateInput!`.
-  *Pre-existing*
-
-- [x] **D.3** `Mutation::Page::BuildFromTemplate` — `buildPageFromTemplate`, `BuildFromTemplateInput!`.
-  *Pre-existing*
-
-- [x] **D.4** Draft lifecycle mutations — all share `Payload::Page::Draft` (item: PageUnion):
-  - `Input::Page::CreateDraft` (templateId), `Mutation::Page::CreateDraft` (createPageDraft)
-  - `Input::Page::DeleteDraft` (id), `Mutation::Page::DeleteDraft` (deleteDraftPage)
-  - `Input::Page::PublishDraft` (id), `Mutation::Page::PublishDraft` (publishDraftPage)
-  *Done 2026-06-07 — 4 specs in `spec/ecoportal/api/graphql/input/page/create_draft_spec.rb`*
-
-- [x] **D.5** `Builder::Page` wired for all template + draft operations:
-  `build_from_template`, `create_from_template`, `create_draft`, `delete_draft`, `publish_draft`.
-  *Done 2026-06-07*
-
----
-
-## Phase E — DataFields (deferred — complex)
-
-> DataFields are the rich content of pages (form fields). 20 field types.
-> Defer until Phases A–D are stable and there is a clear script use case.
-
-- [x] **E.1** All 20 DataField types implemented in `lib/ecoportal/api/graphql/base/page/data_field/`.
-  10 writable types (PlainText, RichText, Date→DateField, Number, Gauge, Select, Checklist,
-  TagField, People, Geo, ContractorEntities, CrossReference, File→FileField, ImageGallery).
-  6 read-only stubs (Signature, Mailbox, ActionsList, Law, AiSummary, Table).
-  TYPE_MAP covers all 20 `__typename` → Ruby class mappings.
-  *Done 2026-06-08 — 68 examples in data_field_spec.rb*
-
-- [x] **E.2** `DataFieldOneToManyInput { additions, updates, deletions }` fully wired:
-  `Collection#mark_for_deletion` + `#dirty_deletions`; `DataFieldAccess#data_fields_deletions`;
-  `Input::Page::Update.from_model` includes deletions in `build_data_fields`.
-  *Done 2026-06-08*
-
-- [x] **E.3** Data field access wired on all page models via `Concerns::DataFieldAccess`
-  included in `Interface::BasePage` (`components`, `field_collection`, `data_fields_updates`,
-  `data_fields_additions`, `data_fields_deletions`). Stage exposes `components` via sections.
-  *Pre-existing + additions from E.2*
-
-- [x] **E.4** Code-spec doc: `.ai-assistance/code/data_fields.md` — all 20 types, setter API,
-  Collection API, DataFieldOneToManyInput wiring, stage-level access, spec coverage table.
-  *Done 2026-06-08*
-
----
-
-## Cross-cutting
-
-- [x] **X.1** `Fragment::BasicPageFields on BasicPage` — sections (id, heading, __typename).
-  *Done 2026-06-07 — fragment/page.rb*
-
-- [x] **X.2** `Fragment::PhasedPageFields on PhasedPage` — stagesIndex, currentStage, activeStages.
-  *Done 2026-06-07 — fragment/page.rb*
-
-- [x] **X.3** `Query::PageDelta` — `pageDelta(deltaInput: [DeltaInput!]!, searchConf: Search)`.
-  Actual schema: takes `{ id, deltaAt: ISO8601DateTime! }` per page, not just ids.
-  Returns `[DeltaResult]` (UPDATED/NOT_FOUND/NEW). `Base::DeltaResult`, `Input::DeltaInput`.
-  *Done 2026-06-07*
-- [x] **X.4** CHANGELOG and version bump — done 2026-06-07, bumped to 1.4.0.
-- [x] **X.5** Cycle-end Gemini review — done 2026-06-07. Finding applied: PAGE_FIELD_KEYS
-  single source of truth in Input::Page.
-
----
-
-## Search integration
-
-> Two modalities — see DECISIONS.md "Two search modalities" entry for full comparison.
-
-- [x] **S.1** Wire `Query::Pages` (org search) for pre-update fetch workflow:
-  documented in `search_filters.md` ("The Required Pattern: Find Before Mutate") and
-  as a code comment on `Query::Pages`. `RegisterPreviewPages` is insufficient — no
-  `patchVer` or field IDs. Both docs explain the required pattern.
-  *Done 2026-06-07*
-
-- [x] **S.2** `Query::RegisterPreviewPages` + `Base::PreviewPage` + `Connection::PreviewPage`.
-  *Done 2026-06-07 — fast ES search, includeArchived supported, presetViewId supported*
-
-- [~] ~~Wire register-scoped page search — `Query::RegisterPreviewPages`:~~
-  `currentOrganization { register(id: $id) { previewPages(searchConf: $conf, includeArchived: $includeArchived, presetViewId: $presetId, ...) } }`
-  Returns `PreviewPage` nodes (ES-backed, fast). No field IDs or `patchVer`.
-  Supports archived pages via `includeArchived: Boolean` (default false).
-  Useful for fast metadata lookup before switching to org search for full data.
-
-- [x] **S.3** `.ai-assistance/code/search_filters.md` — complete filter reference.
-  Extracted from Insomnia_2026-06-07.yaml (real production queries) + Confluence APIDOCS.
-  Covers: find by externalId ✓, find by state ✓, find by location_id ✓, find by date range ✓,
-  nested AND/OR ✓. Also documents: two query modalities, SearchConf structure, silent failure
-  traps, compound archive pattern, operation constants.
-  *Done 2026-06-07*
-
-- [ ] **S.4** Full search filter builder — see dedicated project:
-  `.ai-assistance/projects/search-filter-builder/`