ecoportal-api-graphql 1.3.11 → 1.3.12

data/CLAUDE.md

@@ -11,8 +11,17 @@ docs/worklog.md                          ← current state, blockers, open quest
 .ai-assistance/projects/<slug>/TODO.md   ← active project task list
 .ai-assistance/local/paths.json          ← local paths to sibling repos (gitignored — machine-specific)
 .ai-assistance/bridge/CLAUDE.md          ← bridge protocol: format, lifecycle, cross-repo requests
+.ai-assistance/code/ecoPortal_architecture/  ← VERIFIED PLATFORM KNOWLEDGE — how the platform behaves
+                                            (data model, API layers, page/stage workflows, fields, search).
+                                            Read 00_overview_and_index first, then the area file for the
+                                            task at hand, BEFORE implementing platform logic. See ADR-012.
 ```
 
+> Platform behaviour is documented in `ecoPortal_architecture/` for a reason: do not infer a
+> stage/workflow/field rule from code alone when a verified note exists. If you confirm a new
+> platform fact, add it to the relevant doc with its evidence (`file:line` or "confirmed by
+> &lt;user&gt; on &lt;date&gt;") in the same session -- that tree is the durable, shared home.
+
 ---
 
 ## Repository Role
@@ -95,6 +104,7 @@ the developer explicitly requests it for a specific commit.
 | `spec-generation` | `.ai-assistance/skills/spec-generation/SKILL.md` | Generate RSpec specs for backwards-compat |
 | `refactor` | `.ai-assistance/skills/refactor/SKILL.md` | Identify and log refactoring opportunities |
 | `project-cycle` | `.ai-assistance/skills/project-cycle/SKILL.md` | Project planning, TODOs, decisions |
+| `procedural-memory` | `.ai-assistance/skills/procedural-memory/SKILL.md` | Distill recurring work routines and surface likely next steps |
 
 ---
 

data/docs/self-docs/ARCHITECTURE.md

@@ -0,0 +1,88 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: architecture
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft
+---
+
+# Architecture -- ecoportal-api-graphql
+
+**Scope:** High-level structure only. Deep per-area detail lives in `.ai-assistance/code/`
+(`code-specs`); link to it rather than duplicating.
+
+## Top-level structure
+
+| Directory | Role |
+|---|---|
+| `lib/` | The gem source. `lib/ecoportal/api/graphql/` holds the layered client; `lib/ecoportal/api/common/graphql/` holds shared utilities (HTTP client, base model, helpers, patches). |
+| `spec/` | RSpec specs, mirroring the `lib/` structure. |
+| `tests/` | Manual integration test scripts (live-API characterization, not the RSpec suite). |
+| `bin/` | Development console / helper executables. |
+| `scripts/` | Token-offload and tooling scripts (see `scripts/CLAUDE.md`). |
+| `docs/` | Human docs, worklog, and this self-docs set. |
+| `.ai-assistance/` | AI agent resources: code-specs, project intent/TODOs, skills, bridge, conventions. |
+| `.claude/` | Claude Code settings and hooks for this repo. |
+
+## Key components
+
+Reused from `.ai-assistance/code/OVERVIEW.md` and `.ai-assistance/code/ecoPortal_architecture/`;
+not re-analysed here.
+
+- **Main class `Ecoportal::API::GraphQL`** (`lib/ecoportal/api/graphql.rb`) -- the public entry
+  point, instantiated with credentials (email, pass, org_id, host). Exposes builders and
+  convenience shortcuts per domain.
+- **`Common::GraphQL::Client`** (`lib/ecoportal/api/common/graphql/client.rb`) -- the HTTP layer,
+  extending `Graphlient::Client`. Handles auth (`AuthService`), org context, and timeouts;
+  `no_schema: true` is always passed, so schema introspection is disabled and queries are not
+  validated against a schema at build time.
+- **Layered namespace** under `Ecoportal::API::GraphQL::` (folder mirrors module exactly):
+  `Builder` (developer-facing facade per domain) -> `Query` / `Mutation` (operation definitions)
+  -> `Logic` (execution: base_query, base_model, payload, input, connection) -> `Fragment`
+  (fragment strings) -> `Model` (read-side response models), `Input` / `Payload` (write side) ->
+  `Base` (shared base classes), `Interface` (GraphQL interface types) -> `Common::GraphQL::Client`.
+- **`Compat::` layer** -- v2 compatibility shims (`Pages`, `Registers`, `StageView`,
+  `StageCollection`, etc.) that let `eco-helpers` treat `graphql` as a drop-in for the older `apiv2`
+  interface.
+- **`Diff::` and `Builder::TemplateBuilder`** -- the template build-and-maintenance engine
+  (self-version and cross-object diff, pairing engine + ledger, `Change`-to-`WorkflowCommand`
+  synthesis, unified BUILD emitter). This is where current development is concentrated.
+
+## How they fit
+
+A consumer instantiates `Ecoportal::API::GraphQL` with credentials, then calls a `Builder` for the
+domain it wants (page, template, action, contractor entity, location structure). The builder
+composes `Query`/`Mutation` operations, which the `Logic` layer executes through
+`Common::GraphQL::Client` over HTTP. Fragments are assembled at query build time
+(`BaseQuery#assemble_fragments` scans query strings for `...FragmentName` spreads). Responses parse
+into `Model` objects (read side); mutations take `Input` objects and return `Payload` objects
+(write side). The `Compat` layer re-exposes this so downstream `eco-helpers` scripts keep working
+unchanged.
+
+## Entry points
+
+- `require 'ecoportal/api-graphql'` loads `ecoportal-api-v2` (and transitively `ecoportal-api`),
+  the version file, `ecoportal/api/common.graphql`, then `ecoportal/api/graphql`.
+- Runtime entry is `Ecoportal::API::GraphQL.new(email:, pass:, org_id:, host:)`.
+
+## Build / test tooling
+
+- Build: RubyGems / Bundler. Gem spec: `ecoportal-api-graphql.gemspec`. Version constant:
+  `Ecoportal::API::GRAPQL_VERSION`.
+- Tests: RSpec (`bundle exec rspec`). Live AI tests are `--tag live` and require `ANTHROPIC_API_KEY`
+  loaded from `.env` via `dotenv`.
+- CI: no CI config file was detected at the repo root by the scanner (`ci_files: []`).
+  <!-- TODO(human): confirm whether CI runs elsewhere (e.g. GitLab CI defined outside root) or is absent. -->
+
+## Links to detailed docs
+
+- `.ai-assistance/code/OVERVIEW.md` -- gem overview, entry points, namespace convention.
+- `.ai-assistance/code/ecoPortal_architecture/00_overview_and_index.md` -- verified platform
+  knowledge index (data model, API layers, page/stage workflows, fields, search).
+- `.ai-assistance/code/ecoPortal_architecture/11_integration_gems.md` -- the integration gem stack.
+- `.ai-assistance/code/dependencies.md` -- full dependency map (remotes, fork relationships).
+- `.ai-assistance/code/diff_pairing_engine.md`, `.ai-assistance/code/diff_service_deep_dive.md`,
+  `.ai-assistance/code/template_diff_pairing_domain.md` -- the template diff/build engine.
+- `.ai-assistance/code/data_fields.md`, `.ai-assistance/code/graphql_domain_knowledge.md`,
+  `.ai-assistance/code/schema_analysis.md` -- data-field and schema detail.

data/docs/self-docs/CHANGES.jsonl

@@ -0,0 +1,7 @@
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/OVERVIEW.md", "change": "created", "from_hash": null, "to_hash": "a43c976a85ebfad6"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "created", "from_hash": null, "to_hash": "b0989977a912aab1"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/CONVENTIONS.md", "change": "created", "from_hash": null, "to_hash": "1649159eb799a7b8"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/INTEGRATIONS.md", "change": "created", "from_hash": null, "to_hash": "bae9f91748e33af1"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/STATUS.md", "change": "created", "from_hash": null, "to_hash": "08841d1d45eea2d6"}
+{"ts": "2026-07-06T11:15:00Z", "file": "docs/self-docs/OVERVIEW.md", "change": "updated", "from_hash": "a43c976a85ebfad6", "to_hash": "391055c9a6a687b9"}
+{"ts": "2026-07-06T11:15:00Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "updated", "from_hash": "b0989977a912aab1", "to_hash": "ad05f25b95b49c00"}

data/docs/self-docs/CONVENTIONS.md

@@ -0,0 +1,74 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: conventions
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft
+---
+
+# Conventions -- ecoportal-api-graphql
+
+**Source of truth:** `.rubocop.yml` (repo root) and `CLAUDE.md`. There is no `ai-discovery`
+`conventions.md` in this repo; the below is composed from `.rubocop.yml`, `CLAUDE.md`, and observed
+git history, not re-derived from code.
+
+## Code style
+
+- Indentation: 2 spaces (Ruby default; no override in `.rubocop.yml`).
+- Quotes: not enforced -- `Style/StringLiterals` is disabled, so single and double quotes are both
+  accepted.
+- Line length: unlimited -- `Layout/LineLength` is disabled.
+- Frozen string literal comment: not required (`Style/FrozenStringLiteralComment` disabled).
+- Hash alignment: table style for both colon and hash-rocket (`Layout/HashAlignment`).
+- Dot position: trailing (`Layout/DotPosition`).
+- Alias: prefer `alias_method` (`Style/Alias`).
+- Notable relaxed metrics: `ClassLength` 350, `ModuleLength` 400, `MethodLength` 100,
+  `AbcSize` 30, `CyclomaticComplexity`/`PerceivedComplexity` 30, `ParameterLists` 5.
+- Naming exceptions: camelCase method/variable names are allowed where they mirror GraphQL/Relay
+  schema fields verbatim (`Naming/MethodName` disabled; `clientMutationId` allow-listed). This is
+  intentional -- the client mirrors the schema.
+- Rubocop compliance is required for all generated Ruby: run `bundle exec rubocop <file>` to verify.
+
+## Branch naming
+
+Type-prefixed, slash-separated. Observed prefixes in the branch list and history:
+`feat/<slug>`, `fix/<slug>`, `docs/<slug>`, `chore/<slug>`, and longer-lived `feature/<slug>`
+branches for multi-phase work. Note: `pages` is a long-running primary development branch that
+predates the prefix convention.
+
+## Commit message style
+
+Conventional Commits: `type(scope): message`. Observed types include `feat`, `fix`, `docs`,
+`chore`, and `merge`. Scopes are area-based, e.g. `feat(diff/builder):`, `docs(worklog):`,
+`chore(release):`, `docs(template-automation):`. Release commits follow
+`chore(release): vX.Y.Z ...`.
+
+## Test conventions
+
+- Runner: RSpec (`bundle exec rspec`).
+- Placement: spec files mirror the `lib/` structure under `spec/` (e.g.
+  `spec/ecoportal/api/graphql/input/search_conf_spec.rb`).
+- Live tests: tagged `--tag live`; `.env` is loaded via `dotenv` in `spec_helper.rb`
+  (needs `ANTHROPIC_API_KEY` for live AI tests).
+- Manual integration scripts live under `tests/` (separate from the RSpec suite).
+- Coverage is known to be sparse in subdirectories (see `.ai-assistance/code/spec_coverage.md`).
+
+## Project-specific rules
+
+From `CLAUDE.md`:
+
+- Namespace: `Ecoportal::API::GraphQL` (capital G, Q, L); file paths use lowercase `graphql/`.
+- File/class mirroring: file path mirrors the class namespace exactly.
+- Code-spec docs: for every area analysed, a corresponding `.ai-assistance/code/<area>.md` should
+  exist or be created/updated.
+- No silent breaking changes: any change to the gem's public interface must be noted in the active
+  project's DECISIONS log and confirmed with the developer. Backwards compatibility with
+  `eco-helpers` must be preserved unless explicitly broken.
+- Gemini responses must be verified against actual code before applying.
+- Commit authorship: developer only by default; do not add `Co-Authored-By: Claude ...` unless the
+  developer explicitly requests it.
+- Verified Platform Knowledge: consult `.ai-assistance/code/ecoPortal_architecture/` before
+  implementing platform logic; record newly confirmed platform facts there with evidence (ADR-012).
+- Working-tree safety: follow `.ai-assistance/conventions/code-working-tree-protocol.md` (bridge
+  LOCK, commit overlapping unstaged changes as `wip:` first) before modifying files.

data/docs/self-docs/INTEGRATIONS.md

@@ -0,0 +1,63 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: integrations
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft
+---
+
+# Integrations -- ecoportal-api-graphql
+
+**Purpose:** the ties this project has to other systems and repos. This is the section the central
+hub uses to trace inter-project dependencies and surface reuse (ADR-015 Section 5).
+
+## External services
+
+| Service | Purpose | Notes |
+|---|---|---|
+| ecoPortal GraphQL API | The API this gem is a client for -- reads/writes pages, templates, location structures, contractor entities, actions, organizations. | Auth via `Common::GraphQL::AuthService` (OAuth), scoped by `org_id`; hosted per environment (e.g. live.ecoportal.com). `no_schema: true` -- no introspection. |
+| ecoPortal REST API (v2) | Underlying REST infrastructure the GraphQL layer builds on and stays compatible with via the `Compat` layer. | Provided by the upstream `ecoportal-api-v2` gem. |
+
+## Upstream dependencies (repos we depend on)
+
+| Repo / package | What we use it for |
+|---|---|
+| `ecoportal-api` | REST API base: auth, org context, base models, and the `Ecoportal::API::Common` namespace this gem extends. Team-managed. |
+| `ecoportal-api-v2` | REST API v2 layer (Page, Register, etc.); required by the entry point. Team-managed. Being retired over time. |
+| `graphlient` | Friendly GraphQL DSL/client wrapper; `Common::GraphQL::Client` inherits from `Graphlient::Client`. Active fork owned by the team (upstream: `ashkan18/graphlient`). |
+| `graphql-client` | Low-level GraphQL HTTP + parsing, pulled in transitively via graphlient. Fork for upstream contribution only (upstream: `github-community-projects/graphql-client`); not team-maintained. |
+| `graphql` (graphql-ruby) | Schema definition/execution engine (`rmosolgo/graphql-ruby`); external, read-only reference. Used server-side by ecoPortal; client-side usage here is indirect. |
+
+## Downstream consumers (who depends on us)
+
+- `eco-helpers` -- the primary consumer; an integration-script framework for the ecoPortal
+  Integrations Team. It requires this gem (`ecoportal-api-graphql ~> 1.3, >= 1.3.4`) and relies on
+  the `Compat` layer to treat `graphql` as a drop-in for the older `apiv2` interface. Backwards
+  compatibility with `eco-helpers` must be preserved unless explicitly broken.
+- `ecoportal-qa` -- consumes the gem to verify template deploys (the "verify" step of the template
+  build-and-maintenance pipeline; a `DryRunClient` and `Publisher` were built there). The
+  template-automation project aims to tighten `ecoportal-qa` to consume the gem's page-model.
+
+## Key package dependencies
+
+From `ecoportal-api-graphql.gemspec` (runtime):
+
+- `ecoportal-api` `~> 0.10, >= 0.10.16`
+- `ecoportal-api-v2` `~> 3.3, >= 3.3.3`
+- `graphlient` `>= 0.8.0, < 0.9`
+
+Development: `rspec`, `rubocop` (+ `rubocop-rake`), `rake`, `pry`, `yard`, `redcarpet`.
+Required Ruby: `>= 3.2.2`.
+
+## Feature-request-not-rebuild note
+
+- The template build-and-maintenance capability is developed here in the gem (mechanics: read
+  model, command vocabulary, BUILD emitter, diff, apply, pairing engine + ledger). Orchestration
+  (interactive assisted-resolution UX, session flows) belongs in `eco-helpers`, and verification in
+  `ecoportal-qa`. Before building template/diff/deploy mechanics elsewhere, raise a feature request
+  against this gem rather than duplicating the emission layer.
+- The active template automation is a concrete consumer of the ep-ai-standards
+  `security/ai-service-account-scope` standard: it must authenticate as a dedicated per-org SERVICE
+  ACCOUNT scoped to templates/org-config only, with page records (customer data + PII) structurally
+  out of scope by credential grant. See `.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md`.

data/docs/self-docs/OVERVIEW.md

@@ -0,0 +1,51 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: overview
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft   # draft | reviewed  (only a human sets 'reviewed')
+---
+
+# Overview -- ecoportal-api-graphql
+
+## What this project is
+
+`ecoportal-api-graphql` is a Ruby gem that provides a GraphQL client layer for the ecoPortal
+GraphQL API. It wraps `graphlient` (which itself wraps `graphql-client`) and builds a structured
+layer of models, queries, mutations, fragments, inputs, payloads, and builders on top of it. It
+sits between the upstream ecoPortal REST API gems and downstream consumer code, exposing a
+developer-facing facade for reading and writing ecoPortal domain objects (pages, templates,
+location structures, contractor entities, actions, and organizations).
+
+## Who it serves
+
+Team members -- specifically the ecoPortal Integrations Team and internal script authors. The gem
+is a developer-facing library, not a customer-facing product; its primary consumer is the
+`eco-helpers` integration-script framework. Because it can read and write live customer data
+(page records) through the API, AI caution levels are elevated: the active template-automation
+work is deliberately scoped to a service account covering templates/org-config only, keeping page
+records (customer data + PII) structurally out of scope.
+
+## Current priority
+
+Template Automatic Build and Maintenance (the #1-priority project). This merges the former
+`template-diff-deploy` and `template-maintenance` efforts into one lifecycle: build/maintain 300+
+templates programmatically (a CSV-to-templates pipeline, deadline approximately September 2026)
+and make UAT-to-PROD change replication smooth via a diff/pairing/deploy/verify pipeline. Both
+halves share one emission layer (an ordered `WorkflowCommand` batch with `placeholderId`
+threading).
+
+## At a glance
+
+- Repo type: ruby-gem
+- Primary language / runtime: Ruby (>= 3.2.2)
+- Entry points: `require 'ecoportal/api-graphql'` -> `lib/ecoportal/api-graphql.rb` ->
+  `Ecoportal::API::GraphQL` (`lib/ecoportal/api/graphql.rb`)
+
+## Related self-docs
+
+- Architecture: `ARCHITECTURE.md`
+- Conventions: `CONVENTIONS.md`
+- Integrations: `INTEGRATIONS.md`
+- Status: `STATUS.md`

data/docs/self-docs/STATUS.md

@@ -0,0 +1,69 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: status
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft
+---
+
+# Status -- ecoportal-api-graphql
+
+**Note:** this is the most time-sensitive self-doc. Refresh it at cycle-end and after structural
+changes. Staleness is detectable via `source_head` vs the current git head.
+
+## Active work
+
+Hot paths from the scanner (`lib`, `.ai-assistance`, `spec`, `docs`) plus the active project
+intent. The #1-priority project is Template Automatic Build and Maintenance (see
+`.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md`), which merges the former
+`template-diff-deploy` and `template-maintenance` projects into one lifecycle sharing a single
+`WorkflowCommand` emission layer:
+
+- BUILD: build/maintain 300+ templates programmatically (CSV-to-templates pipeline, deadline
+  approximately September 2026) via a declarative spec -> `Builder::TemplateBuilder` -> ordered
+  command batch -> apply -> verify. Emitter is ready; live characterization is pending sandbox
+  service-account credentials.
+- MAINTAIN / DIFF-DEPLOY: UAT-to-PROD change replication -- detect (diff) -> review -> deploy
+  (delta commands) -> verify -> monitor. Self-version diff, the pairing engine + ledger, diff
+  modalities/`Diff::Strategy`, the cross-object diff path, and `Change`-to-`WorkflowCommand`
+  synthesis are done; the interactive assisted-pairing UX (in `eco-helpers`) is pending.
+- Recent fragment-convention work: Action/ContractorEntity mutations migrated to the spread
+  convention; the query validator now covers mutations.
+
+## Migration state (if any)
+
+- ooze/pages GraphQL-native migration and the api-v2-to-graphql migration are ongoing themes (see
+  `.ai-assistance/projects/ooze-graphql-native-migration/` and `.../api-v2-to-graphql-migration/`).
+  `ecoportal-api-v2` is being retired over time; the `Compat` layer preserves the v2 interface for
+  `eco-helpers` during the transition.
+- Recent releases addressed stale-release drift: v1.3.11 raised the `ecoportal-api-v2` floor to
+  `>= 3.3.3` to fix a Ruby-3.x cascade after three live crashes were traced to version drift.
+
+## Known risks
+
+- Live customer data exposure: the gem can read/write page records (PII). The template automation
+  is the mitigation lever -- it MUST run under a service account scoped to templates/org-config
+  only, enforced by credential grant, not by instruction (ep-ai-standards
+  `security/ai-service-account-scope`). Provisioning that concrete grant is now this repo's work,
+  not a platform blocker.
+- Backwards compatibility with `eco-helpers` is a hard constraint; public-interface changes must be
+  logged in the active project's DECISIONS log and confirmed with the developer.
+- `no_schema: true` means queries are not validated against a schema at build time -- a query
+  validator (now covering mutations) is the compensating control.
+- Spec coverage is sparse in subdirectories (`.ai-assistance/code/spec_coverage.md`).
+
+## Open questions
+
+- No CI config was detected at the repo root; whether CI runs elsewhere or is absent needs human
+  confirmation.
+- The cross-object equivalence-matching (pairing) problem has no stable identity across independent
+  Mongo objects; it depends partly on Product's forthcoming template-entity-id, which this gem
+  bridges and feeds but does not own.
+- Workflow-config-per-stage diff is out of scope until the `PagesWorkflow.stages` read model is
+  completed.
+
+## Recent changes
+
+First generation of the self-docs set (draft, for the EP Projects Register pilot). Generated at
+git head `2abd6fc` on branch `main`. The machine-readable delta is in `CHANGES.jsonl`.

data/docs/self-docs/self-docs-index.json

@@ -0,0 +1,39 @@
+{
+  "schema_version": "1.0",
+  "generated_at": "2026-07-06T11:15:00Z",
+  "repo_name": "ecoportal-api-graphql",
+  "repo_type": "ruby-gem",
+  "head": "2abd6fc",
+  "docs": [
+    {
+      "file": "docs/self-docs/OVERVIEW.md",
+      "purpose": "What the project is, who it serves, current priority",
+      "exists": true,
+      "content_hash": "391055c9a6a687b9"
+    },
+    {
+      "file": "docs/self-docs/ARCHITECTURE.md",
+      "purpose": "Top-level structure, key components, how they fit",
+      "exists": true,
+      "content_hash": "ad05f25b95b49c00"
+    },
+    {
+      "file": "docs/self-docs/CONVENTIONS.md",
+      "purpose": "Coding style, branch naming, commit style, test conventions",
+      "exists": true,
+      "content_hash": "1649159eb799a7b8"
+    },
+    {
+      "file": "docs/self-docs/INTEGRATIONS.md",
+      "purpose": "External services, upstream/downstream repos, dependencies",
+      "exists": true,
+      "content_hash": "bae9f91748e33af1"
+    },
+    {
+      "file": "docs/self-docs/STATUS.md",
+      "purpose": "Active work, migration state, known risks, open questions",
+      "exists": true,
+      "content_hash": "08841d1d45eea2d6"
+    }
+  ]
+}

data/docs/worklog.md

@@ -8,29 +8,6 @@ This file tracks cross-project session state and the overall repo status.
 
 ---
 
-## ▶ SESSION 2026-07-06 — RELEASED the fixed stack; act-gov tagtree + toocs live-green
-
-The 2026-07-05 crash-fixing arc shipped. **All three live-verified green** on act-gov (direct
-`-no-email` runs): **tagtree-update** (created draft → 8 insert / 3 archive → published, no customer
-email) and **toocs-coding** (Oscar confirmed). Released, in dependency order:
-- **ecoportal-api-v2 `v3.3.3`** — Ruby-3.x cascade block-param fix + regression spec.
-- **ecoportal-api-graphql `v1.3.11`** — Diff build+maintenance engine; fragment-convention + Kickstand
-  DateTime fixes; requires v2 >= 3.3.3; validate_queries now covers mutations + hard-fails on render.
-- **eco-helpers `v3.2.17`** — native template build+maintenance + ooze-native; location fragment
-  (`spread :LocationDraft`) + `worfklow` no-email typo fixes; requires gem >= 1.3.11 + v2 >= 3.3.3.
-- **multi_org_api** (`master` + `api-deprecation`) — `-no-email` now forwarded through the rake
-  wrapper + `worfklow` typo fixed (stops customer emails during rake/scheduled tests).
-
-Oscar git-pushed all repos + gem-published; **deploying via server `bundle update ecoportal-api-v2
-ecoportal-api-graphql eco-helpers`** (production Gemfile floors gem>=1.3.9/eco-helpers>=3.2.16, but the
-gemspec floors force v2>=3.3.3 + gem>=1.3.11 transitively). Systemic guard against the recurring
-stale-release drift: raised gemspec dependency FLOORS everywhere + extended `validate_queries.rb`.
-
-**STILL OPEN (non-blocking):** rake `notify_exception` emails the customer on task error regardless of
-`-no-email` — decision pending (suppress / route-to-dev / keep). See [[no-email-leak-paths]].
-
----
-
 ## ▶ SESSION 2026-07-05 — 3 live act-gov crashes = ONE root cause (stale released gems); fixed-stack floors
 
 Three live crashes on act-gov (`-toocs-coding` + org-structure sync), all the **same class**: the

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

@@ -1,54 +1,54 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        class Model
-          module Diffable
-            require_relative 'diffable/hash_diff_nesting'
-            require_relative 'diffable/classic_diff_service'
-            require_relative 'diffable/diff_service'
-
-            DIFF_CLASS = DiffService
-
-            # INSTANCE METHODS
-
-            # @note **cascaded callbacks**
-            #   1. Can **skip** rooted objects (where `root?` is `true`).
-            #     This is because nested rooted objects are usually look-ups
-            #     (not really part of the target model).
-            #   2. Allow to redefine `as_update` on each model.
-            # @param flat [Boolean] whether it should NOT perform a cascaded callback
-            #   througout all the instance objects of the model hierarchy (nested).
-            # @param ignored [Array<String>] the keys that should be ignored, not part
-            #   of the result of `as_update`
-            # @return [nil, Hash] the patch `Hash` model including only
-            #   the changes between `original_doc` and `doc`.
-            def as_update(**kargs)
-              diff_class.new(
-                self,
-                **kargs
-              ).diff
-            end
-
-            # @note `cascaded` will be more accurate in a `GraphQL` scenario.
-            # @return [Boolean] stating if there are changes.
-            def dirty?(...)
-              au = as_update(...)
-
-              return false if au.nil?
-              return false if au == {}
-
-              true
-            end
-
-            private
-
-            def diff_class
-              self.class::DIFF_CLASS
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        class Model
+          module Diffable
+            require_relative 'diffable/hash_diff_nesting'
+            require_relative 'diffable/classic_diff_service'
+            require_relative 'diffable/diff_service'
+
+            DIFF_CLASS = DiffService
+
+            # INSTANCE METHODS
+
+            # @note **cascaded callbacks**
+            #   1. Can **skip** rooted objects (where `root?` is `true`).
+            #     This is because nested rooted objects are usually look-ups
+            #     (not really part of the target model).
+            #   2. Allow to redefine `as_update` on each model.
+            # @param flat [Boolean] whether it should NOT perform a cascaded callback
+            #   througout all the instance objects of the model hierarchy (nested).
+            # @param ignored [Array<String>] the keys that should be ignored, not part
+            #   of the result of `as_update`
+            # @return [nil, Hash] the patch `Hash` model including only
+            #   the changes between `original_doc` and `doc`.
+            def as_update(**kargs)
+              diff_class.new(
+                self,
+                **kargs
+              ).diff
+            end
+
+            # @note `cascaded` will be more accurate in a `GraphQL` scenario.
+            # @return [Boolean] stating if there are changes.
+            def dirty?(...)
+              au = as_update(...)
+
+              return false if au.nil?
+              return false if au == {}
+
+              true
+            end
+
+            private
+
+            def diff_class
+              self.class::DIFF_CLASS
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,43 +1,43 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        class Action < Logic::BaseModel
-          root!
-
-          passkey :id
-          passthrough :altId
-          passthrough :name, :description
-          passthrough :age
-
-          passarray :locationIds
-
-          passthrough :status, :relativeStatus
-          passboolean :archived, :attached, :standaloneAction
-          passthrough :actionCategoryId
-
-          passarray :fileContainerIds
-
-          passarray :assignedPersonMemberIds
-          passthrough :creatorId, :creatorUserId
-          passthrough :updaterId, :updaterUserId
-          passthrough :completerId
-
-          passthrough :timeZone
-          embeds_one :dueDate, klass: Base::DateTime
-          embeds_one :reminderDate, klass: Base::DateTime
-          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 :closedAt, klass: Base::DateTime
-          embeds_one :dueOrClosedDate, klass: Base::DateTime
-
-          passboolean :completed
-          passthrough :closeDetail
-          #passthrough :dueIn # only for templates
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class Action < Logic::BaseModel
+          root!
+
+          passkey :id
+          passthrough :altId
+          passthrough :name, :description
+          passthrough :age
+
+          passarray :locationIds
+
+          passthrough :status, :relativeStatus
+          passboolean :archived, :attached, :standaloneAction
+          passthrough :actionCategoryId
+
+          passarray :fileContainerIds
+
+          passarray :assignedPersonMemberIds
+          passthrough :creatorId, :creatorUserId
+          passthrough :updaterId, :updaterUserId
+          passthrough :completerId
+
+          passthrough :timeZone
+          embeds_one :dueDate, klass: Base::DateTime
+          embeds_one :reminderDate, klass: Base::DateTime
+          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 :closedAt, klass: Base::DateTime
+          embeds_one :dueOrClosedDate, klass: Base::DateTime
+
+          passboolean :completed
+          passthrough :closeDetail
+          #passthrough :dueIn # only for templates
+        end
+      end
+    end
+  end
+end