ecoportal-api-graphql 1.3.10 → 1.3.12

data/lib/ecoportal/api/graphql/input/workflow_command/add_field.rb

@@ -1,18 +1,27 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Input
-        class WorkflowCommand
-          module AddField
-            SCHEMA_VERSION = '20260605'.freeze
-            VALID_KEYS = %i[placeholderId fieldType label stageId sectionId column].freeze
-
-            def self.build(**kwargs)
-              kwargs.slice(*VALID_KEYS).compact
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          module AddField
+            SCHEMA_VERSION = '20260605'.freeze
+            # VERIFIED against the live schema dump (WorkflowAddFieldInput, 20260605): the create
+            # command accepts ONLY these keys. There is NO `description` and NO `required` field on
+            # WorkflowAddFieldInput. `description` is instead a top-level key of
+            # WorkflowEditFieldConfigurationInput, so a field's description is persisted via a
+            # follow-up editFieldConfiguration command (see Builder::TemplateBuilder /
+            # Diff::CommandSynthesizer). `required` has NO input key anywhere in the schema (not on
+            # AddField, not on editFieldConfiguration top-level or any byType sub-input) and so
+            # cannot be persisted through the workflow command bus at all — callers must treat it as
+            # a read-only/unsupported attribute. Do NOT add these keys here (the server rejects them).
+            VALID_KEYS = %i[placeholderId fieldType label stageId sectionId column].freeze
+
+            def self.build(**kwargs)
+              kwargs.slice(*VALID_KEYS).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/interface/location_structure/command.rb

@@ -1,30 +1,30 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Interface
-        module LocationStructure
-          class Command < Logic::BaseModel
-            passkey :id
-            passthrough :state
-
-            def target_ids
-              (doc || {}).values_at(:nodeId, :newId, :id)
-            end
-
-            def keys
-              (doc || {}).keys
-            end
-
-            def set_values(**kargs)
-              kargs.each do |key, value|
-                send(key, value) if respond_to?(key, true)
-              end
-
-              self
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Interface
+        module LocationStructure
+          class Command < Logic::BaseModel
+            passkey :id
+            passthrough :state
+
+            def target_ids
+              (doc || {}).values_at(:nodeId, :newId, :id)
+            end
+
+            def keys
+              (doc || {}).keys
+            end
+
+            def set_values(**kargs)
+              kargs.each do |key, value|
+                send(key, value) if respond_to?(key, true)
+              end
+
+              self
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/logic/input.rb

@@ -1,26 +1,26 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Logic
-        class Input < Logic::BaseModel
-          passthrough :clientMutationId
-
-          class << self
-            # Builds a mutation input hash from a model's diff.
-            # Subclasses override this to reshape fields (e.g. array → IdDiffInput).
-            # @param model [Common::GraphQL::Model] the subject model.
-            # @return [Hash, nil] the mutation input hash, or nil when there are no changes.
-            def from_model(model, client_mutation_id: '')
-              diff = model.as_update
-              return nil if diff.nil?
-
-              diff[:patchVer]         = model.patchVer if model.respond_to?(:patchVer) && !model.patchVer.nil?
-              diff[:clientMutationId] = client_mutation_id unless client_mutation_id.to_s.empty?
-              diff
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Logic
+        class Input < Logic::BaseModel
+          passthrough :clientMutationId
+
+          class << self
+            # Builds a mutation input hash from a model's diff.
+            # Subclasses override this to reshape fields (e.g. array → IdDiffInput).
+            # @param model [Common::GraphQL::Model] the subject model.
+            # @return [Hash, nil] the mutation input hash, or nil when there are no changes.
+            def from_model(model, client_mutation_id: '')
+              diff = model.as_update
+              return nil if diff.nil?
+
+              diff[:patchVer]         = model.patchVer if model.respond_to?(:patchVer) && !model.patchVer.nil?
+              diff[:clientMutationId] = client_mutation_id unless client_mutation_id.to_s.empty?
+              diff
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/mutation/action/archive.rb

@@ -29,7 +29,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/action/create.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/action/update.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__Action
+                  spread :Action
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/contractor_entity/create.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__ContractorEntity
+                  spread :ContractorEntity
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/contractor_entity/destroy.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__ContractorEntity
+                  spread :ContractorEntity
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/contractor_entity/update.rb

@@ -28,7 +28,7 @@ module Ecoportal
                   fullMessages
                 }
                 item {
-                  ___Fragment__ContractorEntity
+                  spread :ContractorEntity
                 }
               }
             end

data/lib/ecoportal/api/graphql/mutation/kickstand/fail_workflow.rb

@@ -27,7 +27,7 @@ module Ecoportal
 
             def default_payload_block
               proc {
-                item { id name status failedAt }
+                item { id name status failedAt { dateTime timeZone } }
                 errors { details fullMessages }
               }
             end

data/lib/ecoportal/api/graphql/mutation/kickstand/start_workflow.rb

@@ -27,7 +27,7 @@ module Ecoportal
 
             def default_payload_block
               proc {
-                item { id name status startedAt }
+                item { id name status startedAt { dateTime timeZone } }
                 errors { details fullMessages }
               }
             end

data/lib/ecoportal/api/graphql/mutation/kickstand/stop_workflow.rb

@@ -27,7 +27,7 @@ module Ecoportal
 
             def default_payload_block
               proc {
-                item { id name status stoppedAt }
+                item { id name status stoppedAt { dateTime timeZone } }
                 errors { details fullMessages }
               }
             end

data/lib/ecoportal/api/graphql.rb

@@ -136,3 +136,4 @@ require_relative 'graphql/mutation'
 require_relative 'graphql/builder'
 require_relative 'graphql/compat'
 require_relative 'graphql/file_upload'
+require_relative 'graphql/diff'

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GRAPQL_VERSION = '1.3.10'.freeze
+    GRAPQL_VERSION = '1.3.12'.freeze
   end
 end

data/tests/dump_template_model.rb

@@ -0,0 +1,90 @@
+require_relative 'local_libs'
+require 'json'
+require 'fileutils'
+
+# Dump a TEMPLATE's GraphQL model to JSON, so a real template can be captured as the golden
+# fixture for the template-editing pipeline (build-from-scratch + diff-and-update).
+#
+# A template IS a page in this API (Query::Templates returns PageUnion nodes), so its structural
+# skeleton — stages -> sections -> components(fields) — comes from the ordinary page model, exactly
+# like tests/dump_page_model.rb. On top of that, this tool also captures the page's *workflow
+# command log* (Query::PagesWorkflowCommands) — the applied command history that drives the
+# workflow builder (callbacks / operations / strategies / recipients config).
+#
+# Two artefacts are written per template:
+#   spec/fixtures/templates/<id>[_<label>].json           -> structural page doc (golden master)
+#   spec/fixtures/templates/<id>[_<label>].commands.json  -> workflow command log (if readable)
+#
+# Usage (run where the GraphQL connection is configured, like the other tests/):
+#   ruby tests/dump_template_model.rb <TEMPLATE_ID> [--out PATH] [--label before|after]
+#
+# Reference target (see .ai-assistance/projects/template-maintenance/DESIGN.md):
+#   ruby tests/dump_template_model.rb 6a3fa5b8f89e07c758df622b --label golden
+#
+# Run --label before / --label after around an executeWorkflowCommands batch to diff exactly
+# what a command sequence changed — the same before/after workflow dump_page_model.rb enables.
+
+def parse_args(argv)
+  opts = { template_id: nil, out: nil, label: nil }
+  rest = argv.dup
+  opts[:template_id] = rest.shift
+  until rest.empty?
+    flag = rest.shift
+    case flag
+    when '--out'   then opts[:out]   = rest.shift
+    when '--label' then opts[:label] = rest.shift
+    else
+      warn "Unknown argument: #{flag}"
+    end
+  end
+  opts
+end
+
+opts = parse_args(ARGV)
+
+unless opts[:template_id]
+  warn 'Usage: ruby tests/dump_template_model.rb <TEMPLATE_ID> [--out PATH] [--label before|after]'
+  exit 1
+end
+
+default_dir  = File.expand_path('../spec/fixtures/templates', __dir__)
+default_name = [opts[:template_id], opts[:label]].compact.join('_')
+struct_path  = opts[:out] || File.join(default_dir, "#{default_name}.json")
+commands_path = File.join(File.dirname(struct_path), "#{File.basename(struct_path, '.json')}.commands.json")
+
+api = Ecoportal::API::GraphQL.new
+
+# 1) Structural skeleton — a template is a page, so fetch it via the page model.
+page = api.pages.get(opts[:template_id])
+
+if page.nil?
+  warn "Could not fetch template '#{opts[:template_id]}' as a page"
+  exit 2
+end
+
+doc = page.respond_to?(:doc) ? page.doc : page.instance_variable_get(:@page)&.doc
+
+FileUtils.mkdir_p(File.dirname(struct_path))
+File.write(struct_path, JSON.pretty_generate(doc))
+
+puts "Dumped template structure '#{opts[:template_id]}' -> #{struct_path}"
+puts "  name:     #{page.respond_to?(:name) ? page.name : '(n/a)'}"
+puts "  patchVer: #{page.respond_to?(:patchVer) ? page.patchVer : '(n/a)'}"
+
+# 2) Workflow command log — the applied-command history behind the workflow builder.
+#    Wrapped in a rescue: the PagesWorkflow read model is still partial (stages is a bare
+#    passarray as of SCHEMA_VERSION 20260605), so treat this as best-effort.
+begin
+  query = Ecoportal::API::GraphQL::Query::PagesWorkflowCommands.new(api.client)
+  commands = []
+  query.each(id: opts[:template_id], first: 100) do |cmd|
+    commands << (cmd.respond_to?(:doc) ? cmd.doc : cmd)
+  end
+  File.write(commands_path, JSON.pretty_generate(commands))
+  puts "Dumped #{commands.size} workflow command(s) -> #{commands_path}"
+rescue StandardError => e
+  warn "Workflow command log not captured (#{e.class}: #{e.message})"
+  warn '  -> structural fixture is still valid; the command log read may be WIP for this org.'
+end
+
+puts 'Tip: capture --label before and --label after an executeWorkflowCommands batch, then diff the JSON.'

data/tests/validate_queries.rb

@@ -41,8 +41,12 @@ client = Ecoportal::API::Common::GraphQL::Client.new(
 )
 schema = GraphQL::Schema.from_introspection(JSON.parse(File.read(schema_path)))
 
-# Collect every concrete query class (recursively, incl. nested like LocationStructure::Draft).
-query_classes = []
+# Collect every concrete query AND mutation class (recursively, incl. nested like
+# LocationStructure::Draft). Mutations are included because a dead fragment reference (e.g. the
+# removed `___Const__Fragment` convention) only surfaces when the operation is RENDERED — and
+# mutations were previously unscanned, which is exactly how the Action/ContractorEntity mutation
+# fragment breakage reached production undetected.
+op_classes = []
 collect = lambda do |mod|
   mod.constants.each do |const|
     obj = begin
@@ -52,20 +56,31 @@ collect = lambda do |mod|
     end
     next unless obj.is_a?(Module)
 
-    query_classes << obj if obj.is_a?(Class) && obj.private_method_defined?(:basic_block)
+    op_classes << obj if obj.is_a?(Class) && obj.private_method_defined?(:basic_block)
     collect.call(obj)
   end
 end
 collect.call(Ecoportal::API::GraphQL::Query)
-query_classes.uniq!
+collect.call(Ecoportal::API::GraphQL::Mutation)
+op_classes.uniq!
 
 structural_bugs = {}
 other_errors    = {}
+render_failures = {}
 render_skips = []
 
-query_classes.sort_by(&:name).each do |klass|
+op_classes.sort_by(&:name).each do |klass|
   inst = klass.new(client)
-  query_str = client.to_query_string(&inst.send(:basic_block))
+  begin
+    query_str = client.to_query_string(&inst.send(:basic_block))
+  rescue NameError => e
+    # The operation cannot even RENDER — an unresolved constant / dead fragment reference
+    # (e.g. the removed `___Const__Fragment` convention pointing at a Fragment:: constant that
+    # no longer exists now that fragments are a registry). Same bug class that crashed the live
+    # LocationDraft / Action / ContractorEntity paths. HARD FAIL.
+    render_failures[klass.name] = ["#{e.class}: #{e.message}"]
+    next
+  end
   fragments = begin
     inst.send(:assemble_fragments, query_str)
   rescue StandardError
@@ -81,9 +96,16 @@ rescue StandardError => e
   render_skips << "#{klass.name} — #{e.class}: #{e.message}"
 end
 
-puts "Validated #{query_classes.size} query classes against #{File.basename(schema_path)}\n\n"
+puts "Validated #{op_classes.size} query + mutation classes against #{File.basename(schema_path)}\n\n"
+
+puts '## FRAGMENT / RENDER FAILURES (fail the build — operation could not render, e.g. dead fragment ref):'
+if render_failures.empty?
+  puts '  none ✅'
+else
+  render_failures.each { |name, msgs| puts "  #{name}\n    - #{msgs.join("\n    - ")}" }
+end
 
-puts '## STRUCTURAL BUGS (fail the build — bare object / over-selected scalar):'
+puts "\n## STRUCTURAL BUGS (fail the build — bare object / over-selected scalar):"
 if structural_bugs.empty?
   puts '  none ✅'
 else
@@ -102,4 +124,4 @@ unless render_skips.empty?
   render_skips.each { |s| puts "  #{s}" }
 end
 
-exit(structural_bugs.empty? ? 0 : 1)
+exit(structural_bugs.empty? && render_failures.empty? ? 0 : 1)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-graphql
 version: !ruby/object:Gem::Version
-  version: 1.3.10
+  version: 1.3.12
 platform: ruby
 authors:
 - Oscar Segura
@@ -160,7 +160,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.2
+        version: 3.3.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -170,7 +170,7 @@ dependencies:
         version: '3.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.3.2
+        version: 3.3.3
 - !ruby/object:Gem::Dependency
   name: graphlient
   requirement: !ruby/object:Gem::Requirement
@@ -219,6 +219,7 @@ files:
 - ".ai-assistance/code/data_fields.md"
 - ".ai-assistance/code/dependencies.md"
 - ".ai-assistance/code/diff_as_input.md"
+- ".ai-assistance/code/diff_pairing_engine.md"
 - ".ai-assistance/code/diff_service_deep_dive.md"
 - ".ai-assistance/code/ecoPortal_architecture/00_overview_and_index.md"
 - ".ai-assistance/code/ecoPortal_architecture/01_terminology_dictionary.md"
@@ -235,12 +236,14 @@ files:
 - ".ai-assistance/code/ecoPortal_architecture/12_ai_documentation_sources_gaps.md"
 - ".ai-assistance/code/ecoPortal_architecture/13_ai_infrastructure.md"
 - ".ai-assistance/code/ecoportal_schema_reference.md"
+- ".ai-assistance/code/filter_contract_matrix.md"
 - ".ai-assistance/code/graphql_domain_knowledge.md"
 - ".ai-assistance/code/refactoring/datafield-readwrite-shape-asymmetry.md"
 - ".ai-assistance/code/refactoring/opportunities.md"
 - ".ai-assistance/code/schema_analysis.md"
 - ".ai-assistance/code/search_filters.md"
 - ".ai-assistance/code/spec_coverage.md"
+- ".ai-assistance/code/template_diff_pairing_domain.md"
 - ".ai-assistance/code/workflow-command-guide.md"
 - ".ai-assistance/code/workflow-space.md"
 - ".ai-assistance/conventions/CLAUDE.md"
@@ -267,15 +270,27 @@ files:
 - ".ai-assistance/projects/graphql-agent/GAP_ANALYSIS.md"
 - ".ai-assistance/projects/ooze-graphql-native-migration/DECISIONS.md"
 - ".ai-assistance/projects/ooze-graphql-native-migration/INTENT.md"
+- ".ai-assistance/projects/ooze-graphql-native-migration/INVENTORY.md"
 - ".ai-assistance/projects/ooze-graphql-native-migration/RISKS.md"
 - ".ai-assistance/projects/ooze-graphql-native-migration/TODO.md"
 - ".ai-assistance/projects/ooze-graphql-native-migration/analysis/2026-06-30-cutover-workflow-deep-review.md"
 - ".ai-assistance/projects/ooze-graphql-native-migration/analysis/2026-07-01-forces-via-workflow-commands-miss-rca.md"
 - ".ai-assistance/projects/page-model/DECISIONS.md"
 - ".ai-assistance/projects/page-model/TODO.md"
+- ".ai-assistance/projects/qa-services-delivery/DECISIONS.md"
+- ".ai-assistance/projects/qa-services-delivery/INTENT.md"
+- ".ai-assistance/projects/qa-services-delivery/PHASE3-SCOPE.md"
+- ".ai-assistance/projects/qa-services-delivery/ROADMAP.md"
+- ".ai-assistance/projects/qa-services-delivery/TODO.md"
 - ".ai-assistance/projects/search-filter-builder/INTENT.md"
 - ".ai-assistance/projects/search-filter-builder/TODO.md"
+- ".ai-assistance/projects/template-automatic-build-maintenance/INTENT.md"
+- ".ai-assistance/projects/template-automatic-build-maintenance/TODO.md"
+- ".ai-assistance/projects/template-diff-deploy/INTENT.md"
+- ".ai-assistance/projects/template-diff-deploy/TODO.md"
 - ".ai-assistance/projects/template-maintenance/DESIGN.md"
+- ".ai-assistance/projects/template-maintenance/PHASE0-FINDINGS.md"
+- ".ai-assistance/projects/template-maintenance/README.md"
 - ".ai-assistance/projects/workflow-space/TODO.md"
 - ".ai-assistance/reinstall-claude-desktop-windows.md"
 - ".ai-assistance/scripts/CLAUDE.md"
@@ -306,6 +321,7 @@ files:
 - ".ai-assistance/skills/gemini-assist/gemini_ask.rb"
 - ".ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt"
 - ".ai-assistance/skills/graphql-schema-analysis/SKILL.md"
+- ".ai-assistance/skills/procedural-memory/SKILL.md"
 - ".ai-assistance/skills/project-cycle/SKILL.md"
 - ".ai-assistance/skills/refactor/SKILL.md"
 - ".ai-assistance/skills/rubocop/SKILL.md"
@@ -332,6 +348,13 @@ files:
 - bin/console
 - bin/setup
 - bin/setup.ps1
+- docs/self-docs/ARCHITECTURE.md
+- docs/self-docs/CHANGES.jsonl
+- docs/self-docs/CONVENTIONS.md
+- docs/self-docs/INTEGRATIONS.md
+- docs/self-docs/OVERVIEW.md
+- docs/self-docs/STATUS.md
+- docs/self-docs/self-docs-index.json
 - docs/worklog.md
 - ecoportal-api-graphql.gemspec
 - lib/ecoportal/api-graphql.rb
@@ -449,6 +472,7 @@ files:
 - lib/ecoportal/api/graphql/builder/register.rb
 - lib/ecoportal/api/graphql/builder/register/preset_view.rb
 - lib/ecoportal/api/graphql/builder/template.rb
+- lib/ecoportal/api/graphql/builder/template_builder.rb
 - lib/ecoportal/api/graphql/compat.rb
 - lib/ecoportal/api/graphql/compat/filter_translator.rb
 - lib/ecoportal/api/graphql/compat/page_reference.rb
@@ -473,6 +497,18 @@ files:
 - lib/ecoportal/api/graphql/connection/person_member.rb
 - lib/ecoportal/api/graphql/connection/preset_view.rb
 - lib/ecoportal/api/graphql/connection/preview_page.rb
+- lib/ecoportal/api/graphql/diff.rb
+- lib/ecoportal/api/graphql/diff/change.rb
+- lib/ecoportal/api/graphql/diff/command_synthesizer.rb
+- lib/ecoportal/api/graphql/diff/cross_object_diff.rb
+- lib/ecoportal/api/graphql/diff/deploy.rb
+- lib/ecoportal/api/graphql/diff/id_resolver.rb
+- lib/ecoportal/api/graphql/diff/pairing/candidate.rb
+- lib/ecoportal/api/graphql/diff/pairing/engine.rb
+- lib/ecoportal/api/graphql/diff/pairing/ledger.rb
+- lib/ecoportal/api/graphql/diff/pairing/signals.rb
+- lib/ecoportal/api/graphql/diff/strategy.rb
+- lib/ecoportal/api/graphql/diff/version_diff.rb
 - lib/ecoportal/api/graphql/error.rb
 - lib/ecoportal/api/graphql/error/locations_error.rb
 - lib/ecoportal/api/graphql/error/locations_error/fetch_nested.rb
@@ -826,6 +862,7 @@ files:
 - tests/contractor_entity_create.rb
 - tests/contractor_entity_udpate.rb
 - tests/dump_page_model.rb
+- tests/dump_template_model.rb
 - tests/loc_structure_get.rb
 - tests/loc_structure_update.rb
 - tests/loc_structures_get.rb