ecoportal-api-graphql 1.3.17 → 2.2.1

data/lib/ecoportal/api/graphql/builder/page.rb

@@ -105,14 +105,6 @@ module Ecoportal
             submitAiSummaryFeedbackMutation.query(**kargs, &block)
           end
 
-          def generate_smart_fill(**kargs, &block)
-            generateSmartFillMutation.query(**kargs, &block)
-          end
-
-          def submit_smart_fill_feedback(**kargs, &block)
-            submitSmartFillFeedbackMutation.query(**kargs, &block)
-          end
-
           private
 
           # Blank the page's externalId via updatePage (no patchVer needed — cleanup path).
@@ -184,14 +176,6 @@ module Ecoportal
             Mutation::AiSummary::SubmitFeedback.new(client)
           end
 
-          def generateSmartFillMutation
-            Mutation::SmartFill::Generate.new(client)
-          end
-
-          def submitSmartFillFeedbackMutation
-            Mutation::SmartFill::SubmitFeedback.new(client)
-          end
-
           def executeWorkflowCommandsMutation
             Mutation::Page::ExecuteWorkflowCommands.new(client)
           end

data/lib/ecoportal/api/graphql/builder/template.rb

@@ -40,10 +40,48 @@ module Ecoportal
             )
           end
 
+          # Edits an existing related-pages entry. Only the keys you pass are sent — absent keys
+          # are left alone server-side, so this is a partial update, not a replace.
+          def update_related_page(template_id:, id:, patch_ver:, title: nil, register_id: nil, filters: nil, &block)
+            updateRelatedPageMutation.query(
+              template_id: template_id,
+              id:          id,
+              patch_ver:   patch_ver,
+              title:       title,
+              register_id: register_id,
+              filters:     filters,
+              &block
+            )
+          end
+
           def destroy_related_page(template_id:, id:, patch_ver:, &block)
             destroyRelatedPageMutation.query(template_id: template_id, id: id, patch_ver: patch_ver, &block)
           end
 
+          # TEMPLATE CHANGE LOG — who changed this template, what, and when. Newest first
+          # (server-side `_id: :desc`), paginated.
+          #
+          #   api.template.change_log(id: template_page_id, first: 50)   # => Connection
+          #   api.template.change_log.each(id: template_page_id) { |e| ... }  # auto-paginates
+          #
+          # ★ Two caveats, both silent — read `Base::Template::ChangeLogEntry` before relying on
+          # this: the connection is nil (not empty) unless the caller satisfies
+          # `Pages::TemplatePolicy#update_information?`, and only TEMPLATE_BUILDER-sourced
+          # commands appear (workflow-builder ones are on `Query::PagesWorkflowCommands`).
+          #
+          # Called with no arguments it returns the query object itself, so `#each` /`#map` and
+          # the rest of Enumerable are available — same idiom as the QueryIntegration queries on
+          # `Model::Organization`.
+          # @param detail [Boolean] when true, also select FIELD-LEVEL detail (what changed).
+          #   Ignored when an explicit block is given -- the block wins, since it is the more
+          #   specific instruction. Off by default so the common who/when read stays cheap.
+          def change_log(detail: false, **kargs, &block)
+            selection = block || (detail ? Query::TemplateChangeLog.detail_block : nil)
+            return changeLogQuery if kargs.empty? && !selection
+
+            changeLogQuery.query(**kargs, &selection)
+          end
+
           private
 
           def createMutation
@@ -70,9 +108,17 @@ module Ecoportal
             Mutation::Template::CreateRelatedPage.new(client)
           end
 
+          def updateRelatedPageMutation
+            Mutation::Template::UpdateRelatedPage.new(client)
+          end
+
           def destroyRelatedPageMutation
             Mutation::Template::DestroyRelatedPage.new(client)
           end
+
+          def changeLogQuery
+            Query::TemplateChangeLog.new(client)
+          end
         end
       end
     end

data/lib/ecoportal/api/graphql/builder/template_builder.rb

@@ -24,7 +24,12 @@ module Ecoportal
         #           { field_type: 'PlainText', label: 'Description', column: 0,
         #             description: 'ID:token' },   # addField (+ editFieldConfiguration for description)
         #           { field_type: 'Select', label: 'Severity',
-        #             options: [ { label: 'Low', weight: 0 }, ... ],                # addSelectFieldOption
+        #             options: [ { label: 'Low', weight: 0, value: 'low' },
+        #                        { label: 'High', weight: 10, value: 'high' } ], # addSelectFieldOption
+        #             # `value:` is REQUIRED per option (backend: AddSelectFieldOptionInput,
+        #             # required: true) — it is the option's unique key (duplicate values within one
+        #             # field are rejected), always sent as a String even for numeric select fields
+        #             # (stored as an Integer server-side). A missing `value` raises ArgumentError.
         #             config: { select: { multiple: false } } },                   # editFieldConfiguration(byType:)
         #           { field_type: 'Gauge', label: 'Risk',
         #             stops: [ { threshold: 0, color: '#0f0' }, ... ],              # addGaugeFieldStop
@@ -125,9 +130,23 @@ module Ecoportal
             add(:editFieldConfiguration, data_field_id: field_ph, description: description)
           end
 
+          # addSelectFieldOption requires `value` (backend: AddSelectFieldOptionInput, required: true
+          # — a real field distinct from label/weight, cast to a number server-side for numeric
+          # select fields). The DSL has no natural default for it (unlike label/weight, it is
+          # business data this builder cannot infer), so it MUST be supplied per option in the spec;
+          # a missing one raises rather than silently falling back to the label/weight (which would
+          # risk persisting the wrong stored value for a scored/numeric select field).
           def emit_options(field, field_ph)
             Array(field[:options]).each do |opt|
-              add(:addSelectFieldOption, data_field_id: field_ph, label: opt[:label], weight: opt[:weight])
+              value = opt[:value]
+              if value.nil?
+                raise ArgumentError,
+                      "TemplateBuilder: option '#{opt[:label]}' on field '#{field[:label]}' is " \
+                      'missing `value` (addSelectFieldOption requires it) — supply ' \
+                      'options: [{ label:, weight:, value: }, ...] in the spec'
+              end
+
+              add(:addSelectFieldOption, data_field_id: field_ph, label: opt[:label], value: value, weight: opt[:weight])
             end
           end
 

data/lib/ecoportal/api/graphql/compat/pages.rb

@@ -18,8 +18,13 @@ module Ecoportal
           # Fetch a page by ID with full data — metadata, stages, sections, data fields.
           # When stage_id is provided, wraps the result in a StageView that filters
           # sections and components to that stage only — matching v2 per-stage behaviour.
-          def get(id, stage_id: nil)
-            page = Query::Page.new(@client).query(id: id) do
+          # @param variables [Hash] optional CommonPageUnion document-variable overrides
+          #   (`showHiddenData:`, `content:`, `only_content:`, `fields:`). `content: false`
+          #   skips field values AND `attachedFiles` — the one selection preauthorized on the
+          #   `files: download` ability — so structure-only readers (e.g. template tooling on a
+          #   least-privilege account) can read pages without that grant.
+          def get(id, stage_id: nil, **variables)
+            page = Query::Page.new(@client).query(id: id, **variables) do
               spread :CommonPageUnion
             end
             stage_id ? StageView.new(page, stage_id) : page

data/lib/ecoportal/api/graphql/compat/response.rb

@@ -5,7 +5,21 @@ module Ecoportal
         # Wraps a GraphQL mutation payload to expose the v2-compatible response interface.
         # Scripts check .success? and .status after update/create operations.
         class Response
+          # The payload contract this wrapper delegates to. Guarded at construction so a
+          # payload of the wrong shape fails LOUD here, instead of silently downstream.
+          # This is the class of drift behind the eco-helpers 3.2.19 KPI-counter
+          # regression, where a Compat::Response (duck-typed, not a Common::Response)
+          # slipped through an `is_a?` check and every GraphQL update went uncounted.
+          PAYLOAD_CONTRACT = %i[success? error? error_doc item].freeze
+
           def initialize(payload)
+            missing = PAYLOAD_CONTRACT.reject { |meth| payload.respond_to?(meth) }
+            unless missing.empty?
+              raise ArgumentError,
+                    "Compat::Response payload #{payload.class} does not honour the expected " \
+                    "response contract; missing: #{missing.join(', ')}"
+            end
+
             @payload = payload
           end
 

data/lib/ecoportal/api/graphql/concerns/threadable.rb

@@ -0,0 +1,58 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Concerns
+        # Bounded-concurrency helpers for batch operations.
+        #
+        # Ported from `ecoportal-api-v2`'s `Common::Concerns::Threadable` rather than required
+        # from it: that gem is being decommissioned, and this is exactly the kind of small,
+        # stable primitive that should not create a new dependency on it.
+        #
+        # `new_thread` keeps at most `max` threads alive by joining the oldest before starting
+        # a new one — a deliberately simple back-pressure valve, not a pool. `max: 1` runs
+        # inline (no threads at all), which keeps single-file paths and specs deterministic.
+        module Threadable
+          private
+
+          # @param threads [Array<Thread>] the caller's thread accumulator (joined by the caller).
+          # @param max [Integer] maximum concurrent threads; `1` means run inline.
+          # @return [Array<Thread>, void]
+          def new_thread(threads, max: 20, &block)
+            if max <= 1
+              yield
+              return []
+            end
+
+            threads.shift.join if threads.count >= max
+            threads << Thread.new(&block)
+          end
+
+          # Named mutexes, created on demand. Use one key per shared resource so unrelated
+          # critical sections never serialise against each other.
+          def mutex(key = :general)
+            key           = key.to_sym
+            @mutex_map  ||= {}
+            # The map itself must be created atomically the first time.
+            @mutex_map[key] ||= Mutex.new
+          end
+
+          # Batch work must not be killed by one file raising in a thread, and must not spam
+          # the caller's stderr with per-thread reports — the caller gets the error in its
+          # result object instead. Restores both globals afterwards.
+          def with_preserved_thread_globals(abort: false, report: false)
+            mutex(:thread_globals).synchronize do
+              prev_abort  = Thread.abort_on_exception
+              prev_report = Thread.report_on_exception
+              Thread.abort_on_exception  = abort
+              Thread.report_on_exception = report
+              yield
+            ensure
+              Thread.abort_on_exception  = prev_abort
+              Thread.report_on_exception = prev_report
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/concerns.rb

@@ -12,3 +12,4 @@ require_relative 'concerns/fragment_definitions'
 require_relative 'concerns/snake_camel_access'
 require_relative 'concerns/page_compat'
 require_relative 'concerns/data_field_access'
+require_relative 'concerns/threadable'

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

@@ -3,7 +3,7 @@ module Ecoportal
     class GraphQL
       module Connection
         class Action < Logic::Connection
-          class_resolver :node_class, Model::Action
+          nodes_of Model::Action
         end
       end
     end

data/lib/ecoportal/api/graphql/connection/action_category.rb

@@ -3,7 +3,7 @@ module Ecoportal
     class GraphQL
       module Connection
         class ActionCategory < Logic::Connection
-          class_resolver :node_class, Base::ActionCategory
+          nodes_of Base::ActionCategory
         end
       end
     end

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

@@ -0,0 +1,11 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Connection
+        class Activity < Logic::Connection
+          nodes_of Model::Activity
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/connection/activity_log.rb

@@ -0,0 +1,11 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Connection
+        class ActivityLog < Logic::Connection
+          nodes_of Model::ActivityLog
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/connection/auth_log.rb

@@ -0,0 +1,11 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Connection
+        class AuthLog < Logic::Connection
+          nodes_of Model::AuthLog
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/connection/contractor_entity.rb

@@ -3,7 +3,7 @@ module Ecoportal
     class GraphQL
       module Connection
         class ContractorEntity < Logic::Connection
-          class_resolver :node_class, Model::ContractorEntity
+          nodes_of Model::ContractorEntity
         end
       end
     end

data/lib/ecoportal/api/graphql/connection/minimal_dashboard.rb

@@ -0,0 +1,11 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Connection
+        class MinimalDashboard < Logic::Connection
+          nodes_of Model::MinimalDashboard
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/connection/page.rb

@@ -3,7 +3,7 @@ module Ecoportal
     class GraphQL
       module Connection
         class Page < Logic::Connection
-          class_resolver :node_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
+          nodes_of 'Ecoportal::API::GraphQL::Model::PageUnion'
         end
       end
     end

data/lib/ecoportal/api/graphql/connection/pages_workflow_command.rb

@@ -5,7 +5,7 @@ module Ecoportal
         class PagesWorkflowCommand < Logic::Connection
           SCHEMA_VERSION = '20260605'.freeze
 
-          class_resolver :node_class, 'Ecoportal::API::GraphQL::Base::PagesWorkflow::CommandInterface'
+          nodes_of 'Ecoportal::API::GraphQL::Base::PagesWorkflow::CommandInterface'
         end
       end
     end

data/lib/ecoportal/api/graphql/connection/person_member.rb

@@ -3,7 +3,7 @@ module Ecoportal
     class GraphQL
       module Connection
         class PersonMemberConnection < Logic::Connection
-          class_resolver :node_class, Model::PersonMember
+          nodes_of Model::PersonMember
         end
       end
     end

data/lib/ecoportal/api/graphql/connection/person_member_changelog.rb

@@ -0,0 +1,11 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Connection
+        class PersonMemberChangelog < Logic::Connection
+          nodes_of Model::PersonMemberChangelog
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/connection/preview_page.rb

@@ -3,7 +3,7 @@ module Ecoportal
     class GraphQL
       module Connection
         class PreviewPage < Logic::Connection
-          class_resolver :node_class, 'Ecoportal::API::GraphQL::Model::PreviewPage'
+          nodes_of 'Ecoportal::API::GraphQL::Model::PreviewPage'
         end
       end
     end

data/lib/ecoportal/api/graphql/connection/template_change_log.rb

@@ -0,0 +1,19 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Connection
+        # `Template.commands` — a `PagesWorkflowCommandInterfaceConnection` carrying
+        # `totalCount` (added by `Types::CustomConnections::BaseConnection`), `pageInfo`
+        # and `nodes`.
+        #
+        # ★ A nil connection here means NOT PERMITTED, not "no changes" — see
+        # `Base::Template::ChangeLogEntry` for the two access caveats.
+        class TemplateChangeLog < Logic::Connection
+          # `nodes_of` (not `class_resolver :node_class`) — see Logic::Connection for why the
+          # shared dynamic collection poisons sibling connections otherwise.
+          nodes_of Model::Template::ChangeLogEntry
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/connection.rb

@@ -15,3 +15,9 @@ require_relative 'connection/page'
 require_relative 'connection/preview_page'
 require_relative 'connection/preset_view'
 require_relative 'connection/pages_workflow_command'
+require_relative 'connection/activity'
+require_relative 'connection/activity_log'
+require_relative 'connection/auth_log'
+require_relative 'connection/person_member_changelog'
+require_relative 'connection/minimal_dashboard'
+require_relative 'connection/template_change_log'

data/lib/ecoportal/api/graphql/diff/change.rb

@@ -23,13 +23,18 @@ module Ecoportal
         # that parent_id alone cannot carry. Set for an ADDED :field (parent_id = its section id,
         # owner_id = its stage id) because addField requires BOTH sectionId and stageId (both
         # NON_NULL in the schema). nil for every other kind/op.
+        #
+        # value: for an ADDED :option, the select option's `value` (the schema's addSelectFieldOption
+        # requires it — see AddSelectFieldOptionInput, backend authority). Read from the source doc's
+        # option.value (VersionDiff#index_options); nil when the source doc did not carry one. NEVER
+        # defaulted to label/weight by the synthesiser — see CommandSynthesizer#option_command.
         Change = Struct.new(:op, :kind, :id, :label, :path, :attribute, :before, :after, :parent_id,
-                            :by_type, :owner_id, keyword_init: true) do
+                            :by_type, :owner_id, :value, keyword_init: true) do
           def to_h
             {
               op: op, kind: kind, id: id, label: label, path: path,
               attribute: attribute, before: before, after: after, parent_id: parent_id,
-              by_type: by_type, owner_id: owner_id
+              by_type: by_type, owner_id: owner_id, value: value
             }.compact
           end
 

data/lib/ecoportal/api/graphql/diff/command_synthesizer.rb

@@ -277,13 +277,31 @@ module Ecoportal
 
             field_ref = ref(field_id)
             case change.op
-            when :added   then build(:addSelectFieldOption, data_field_id: field_ref, label: change.label)
+            when :added   then add_option(change, field_ref)
             when :removed then build(:removeSelectFieldOption, data_field_id: field_ref, option_id: change.id)
             when :changed then edit_option(change, field_ref)
             else unsupported!(change)
             end
           end
 
+          # addSelectFieldOption requires `value` (backend: AddSelectFieldOptionInput, required: true
+          # — a real, distinct field from label/weight; see OptionType#value). NEVER default it to
+          # the label/weight (a numeric select field stores `value` as a number, so a label stand-in
+          # would silently persist wrong data). When the source doc's option carried no `value`
+          # (Change#value nil — see VersionDiff#index_options), raise loudly instead of guessing.
+          def add_option(change, field_ref)
+            if change.value.nil?
+              raise ArgumentError,
+                    "CommandSynthesizer: cannot build addSelectFieldOption for option " \
+                    "'#{change.label}' (field #{field_ref}) — Change#value is nil. The source doc's " \
+                    "option is missing `value` (VersionDiff#index_options reads it from " \
+                    "option['value']); supply it on the source doc, or on the Change directly when " \
+                    "hand-assembling one."
+            end
+
+            build(:addSelectFieldOption, data_field_id: field_ref, label: change.label, value: change.value)
+          end
+
           def edit_option(change, field_id)
             case change.attribute
             when 'label'  then build(:editSelectFieldOption, data_field_id: field_id, option_id: change.id, label: change.after)

data/lib/ecoportal/api/graphql/diff/pairing/signals.rb

@@ -25,13 +25,33 @@ module Ecoportal
             # MISMATCH scores 0 rather than vetoing (the field may have been re-purposed keeping its
             # genome, or genome may be absent on newer field types). Returns nil when neither side
             # carries a genome — the signal simply does not apply and is excluded from the average.
+            #
+            # LINEAGE (verified live 2026-08-05, same-org backup restore of a full template): a
+            # restore does NOT equal-copy the signature — it APPENDS one segment to it, for every
+            # membrane AND force (e.g. `2zwxkb6gns` → `2zwxkb6gns53jp`, `ktnrya` → `ktnrya877l`;
+            # 28/28 fields + 4/4 forces followed the rule). So an ancestor's signature is a strict
+            # PREFIX of its descendant's, and equality-only scoring would give the exact
+            # cross-object case this engine exists for (UAT backup → PROD restore) a 0.0 — worse
+            # than no signal. Prefix ancestry therefore scores just below an exact match.
             def genome(source, target)
               a = source['genomeSignature']
               b = target['genomeSignature']
               return nil if blank?(a) && blank?(b)
               return 0.0 if blank?(a) || blank?(b)
+              return 1.0 if a == b
 
-              a == b ? 1.0 : 0.0
+              lineage?(a, b) ? 0.9 : 0.0
+            end
+
+            # True when one signature is a strict prefix of the other (restore/copy appends a
+            # lineage segment — see #genome). Direction is unknowable at a pairing call (either
+            # side may be the older document), so both directions count. Very short signatures
+            # are rejected as ancestry evidence — a trivial prefix can collide by chance.
+            def lineage?(sig_a, sig_b)
+              short, long = [sig_a.to_s, sig_b.to_s].minmax_by(&:length)
+              return false if short.length < 4
+
+              short != long && long.start_with?(short)
             end
 
             # Field type (__typename) equality. A type change is a strong DISQUALIFIER for a data

data/lib/ecoportal/api/graphql/diff/version_diff.rb

@@ -91,8 +91,11 @@ module Ecoportal
           # addStageSection.stageId), threading through a placeholder when the parent is created in
           # the same batch. nil (default) means no parent id is known/recorded — the historical
           # behaviour, unchanged.
-          def diff_index(kind, before_idx, after_idx, label:, path:, parent: nil, owner: nil, &compare)
-            procs   = { label: label, path: path, parent: parent, owner: owner }
+          # `value:` (optional proc) is recorded on ADDED changes only — currently used for :option,
+          # whose addSelectFieldOption command requires the source doc's option.value (see
+          # Change#value). nil (default) means the kind has no `value` concept.
+          def diff_index(kind, before_idx, after_idx, label:, path:, parent: nil, owner: nil, value: nil, &compare)
+            procs   = { label: label, path: path, parent: parent, owner: owner, value: value }
             removed = (before_idx.keys - after_idx.keys).map { |id| removed_change(kind, id, before_idx[id], procs) }
             added   = (after_idx.keys - before_idx.keys).map { |id| added_change(kind, id, after_idx[id], procs) }
             matched = (before_idx.keys & after_idx.keys).flat_map { |id| Array(compare.call(id, before_idx[id], after_idx[id])) }
@@ -105,7 +108,8 @@ module Ecoportal
 
           def added_change(kind, id, info, procs)
             Change.new(op: :added, kind: kind, id: id, label: procs[:label].call(info), path: procs[:path].call(info),
-                       parent_id: procs[:parent]&.call(info), owner_id: procs[:owner]&.call(info))
+                       parent_id: procs[:parent]&.call(info), owner_id: procs[:owner]&.call(info),
+                       value: procs[:value]&.call(info))
           end
 
           def stage_changes
@@ -153,7 +157,7 @@ module Ecoportal
 
           def options_diff(field_id, path, before_field, after_field)
             diff_index(:option, index_options(before_field), index_options(after_field),
-                       label: ->(o) { o[:label] }, path: ->(_o) { path }) do |k, b, a|
+                       label: ->(o) { o[:label] }, path: ->(_o) { path }, value: ->(o) { o[:value] }) do |k, b, a|
               cmp = []
               cmp << changed(:option, k, a[:label], path, 'label', b[:label], a[:label], field_id) if b[:label] != a[:label]
               cmp << changed(:option, k, a[:label], path, 'weight', b[:weight], a[:weight], field_id) if b[:weight] != a[:weight]
@@ -294,13 +298,16 @@ module Ecoportal
           end
 
           # Options keyed by id when present, else by value (primary) / name (auxiliary) — the
-          # correct select-option identity (NOT genome).
+          # correct select-option identity (NOT genome). `value` is carried through separately from
+          # `label` (they are distinct schema fields — OptionType#value vs #label/#name) so an ADDED
+          # option's Change can supply the real value addSelectFieldOption requires, never a
+          # label/weight stand-in.
           def index_options(field)
             Array(field['options']).each_with_object({}) do |o, h|
               next unless o.is_a?(Hash)
 
               key = o['id'] || o['value'] || o['label'] || o['name']
-              h[key] = { label: o['label'] || o['name'] || o['value'], weight: o['weight'] }
+              h[key] = { label: o['label'] || o['name'] || o['value'], weight: o['weight'], value: o['value'] }
             end
           end