ecoportal-api-graphql 1.3.17 → 2.2.1

data/lib/ecoportal/api/common/graphql/http_client.rb

@@ -2,7 +2,88 @@ module Ecoportal
   module API
     module Common
       module GraphQL
-        class ResponseError < StandardError; end
+        # Raised when a 200 response carries a top-level `errors[]` array.
+        #
+        # ★ Carries the RAW error entries, so `extensions` survives. Before this, the
+        # class collapsed the response into the joined `message` text and threw the rest
+        # away — which made it impossible for Ruby tooling to tell a permission problem
+        # from a request problem, the exact diagnosis we tell customers to perform.
+        # Tracked as Q-27 in `docs/open-questions.md`.
+        #
+        # The backend's error contract (`app/graphql/eco_portal_schema.rb`, verified
+        # 2026-09-01) puts these keys under `extensions`:
+        #
+        # | key            | when                     | shape |
+        # |----------------|--------------------------|-------|
+        # | `code`         | always                   | string: `unauthorized`, `document_not_found`, `unprocessable_entity`, `write_conflict`, `internal_server_error`, … |
+        # | `fullMessages` | `unauthorized`           | array of human strings (`exp.result.reasons.full_messages`) |
+        # | `details`      | `unauthorized`           | ActionPolicy `reasons.details` — usually a Hash whose **key names the failing policy** and whose value lists the rules |
+        # | `problems`     | validation, and only when the server runs with `SHOW_GRAPHQL_EXCEPTION` | record errors |
+        #
+        # ⚠ `details` is NOT reliably a Hash. Two call sites emit an Array instead
+        # (`mutations/pages/send_as_email.rb` sends inaccessible ids;
+        # `queries/pages/templates/fetcher.rb` sends `[msg]`). Accessors here therefore
+        # return whatever the server sent, unwrapped but uncoerced — callers must not
+        # assume a shape.
+        class ResponseError < StandardError
+          # @return [Array<Hash>] the raw `errors[]` entries, exactly as received.
+          attr_reader :errors
+
+          # @param msg [String, nil] explicit message; defaults to the joined error messages.
+          # @param errors [Array<Hash>] raw top-level `errors[]` entries.
+          def initialize(msg = nil, errors: [])
+            @errors = Array(errors)
+            super(msg || build_message)
+          end
+
+          # @return [Array<Hash>] the `extensions` object of each error that carried one.
+          def extensions
+            errors.filter_map { |err| err['extensions'] }
+          end
+
+          # @return [Array<String>] every `extensions.code` present, in order.
+          def codes
+            extensions.filter_map { |ext| ext['code'] }
+          end
+
+          # ★ The fastest way to tell a permission problem from a request problem.
+          # @return [Array] every `extensions.details` present. Shape is the server's —
+          #   typically a Hash keyed by the failing policy, but sometimes an Array.
+          def details
+            extensions.filter_map { |ext| ext['details'] }
+          end
+
+          # @return [Array<String>] flattened `extensions.fullMessages`.
+          def full_messages
+            extensions.flat_map { |ext| Array(ext['fullMessages']) }
+          end
+
+          # @return [Boolean] whether ANY error was an authorization refusal. Use this to
+          #   branch on "you cannot" vs "that request was wrong" — do not pattern-match
+          #   the message text, which is prose and drifts.
+          def unauthorized?
+            codes.include?('unauthorized')
+          end
+
+          private
+
+          # The joined messages stay FIRST and unchanged, so existing callers matching on
+          # the message text keep working; the diagnosis is appended after them.
+          def build_message
+            base = errors.filter_map { |err| err['message'] }.join('; ')
+            base = 'GraphQL request failed' if base.empty?
+            [base, diagnosis].compact.join(' | ')
+          end
+
+          def diagnosis
+            parts = []
+            parts << "code: #{codes.uniq.join(', ')}" if codes.any?
+            parts << "details: #{details.inspect}"    if details.any?
+            return if parts.empty?
+
+            parts.join(' | ')
+          end
+        end
 
         class HttpClient < Common::Client
           class << self
@@ -184,7 +265,9 @@ module Ecoportal
 
             parsed = response.body
             errors = parsed && parsed['errors']
-            raise ResponseError, errors.map { |e| e['message'] }.join('; ') if errors&.any?
+            # Pass the raw entries through: `extensions` (and therefore the failing
+            # policy under `extensions.details`) is the whole point — see Q-27.
+            raise ResponseError.new(errors: errors) if errors&.any?
 
             parsed
           end

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,38 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # A single "System Access Log" entry, returned by
+        # `currentOrganization.activityLogs` (ActivityLogUnionConnection). Read-only.
+        #
+        # `ActivityLogUnion` is a UNION over 9 members:
+        #   DashboardAccess, DashboardCreate, DashboardDelete, DashboardUpdate,
+        #   DeniedDashboardAccess, DeniedPageAccess, FileDownload, PageAccess,
+        #   ScimIntegrationAccess.
+        # This models the field set COMMON to ALL members and passes the concrete
+        # `__typename` through. The Dashboard* members additionally expose
+        # `parentResource*` + `resource` (see Model::ActivityLog); page/file/scim
+        # members do not, so those live on the Model subclass as nullable embeds.
+        #
+        # Enum-valued fields are exposed as plain strings:
+        # - resourceType: ResourceTypesEnum
+        class ActivityLog < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          # Concrete member type (e.g. 'DashboardAccess', 'PageAccess', 'FileDownload').
+          passthrough :__typename
+          passthrough :activityType
+          passthrough :source
+          passthrough :userType
+          passthrough :accountStatus
+          passthrough :becomingEmail
+          # content: Hash! — free-form activity payload; passed through as a Hash.
+          passthrough :content
+          passthrough :resourceId, :resourceName, :resourceType
+          embeds_one :createdAt, klass: Base::DateTime
+        end
+      end
+    end
+  end
+end

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

@@ -2,14 +2,19 @@ module Ecoportal
   module API
     class GraphQL
       module Base
-        # Represents one generation version of an AiSummary field.
-        # Returned by generateAiSummary — tracks the prompt, output, token usage, and status.
+        # One generation version of an AI page summary — the `item` of `generatePageSummary`.
+        #
+        # ★ Corrected 2026-07-30 against the live schema. The previous declarations (`prompt`,
+        # `inputTokens`, `outputTokens`, `totalTokens`, `resourceType`, `ratings`) do not exist on
+        # `AiSummaryVersion` and always read nil. The real fields are: aiSummary, alreadyRated,
+        # createdAt, dataFieldLogs, generationErrors, id, pagePatchVer, status.
+        #
+        # `dataFieldLogs` / `generationErrors` / `createdAt` are left unmodelled until their own
+        # shapes are verified — select and model them deliberately rather than by assumption.
         class AiSummaryVersion < Logic::BaseModel
-          passkey :id
-          passthrough :aiSummary, :status, :prompt
-          passthrough :inputTokens, :outputTokens, :totalTokens
-          passthrough :resourceType # "field" | "stage" | "page"
-          passarray :ratings        # [[user_id, score], ...]
+          passkey     :id
+          passthrough :aiSummary, :status, :pagePatchVer
+          passboolean :alreadyRated
         end
       end
     end

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

@@ -0,0 +1,24 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # System access log entry (SCIM / security auditing), returned by
+        # `Organization.authLogs`. Read-only.
+        #
+        # Enum-valued fields are exposed as plain strings:
+        # - event: 'LOGIN' | 'LOGOUT' | 'PASSWORD_CHANGE' | 'PASSWORD_RESET_REQUEST'
+        # - loginMethod: 'PASSWORD' | 'SAML' | 'MAGIC_LINK' | 'REDIRECT' | 'OAUTH'
+        # - source: 'WEB' | 'MOBILE'
+        class AuthLog < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :event, :source
+          passthrough :loginMethod
+          passthrough :host, :ipAddress, :referrer, :userAgent
+          embeds_one :createdAt, klass: Base::DateTime
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # AuthorizationResult — the result of a permission / ability check (a `canXXX` field).
+        #   value:   Boolean!  — whether the action is allowed
+        #   message: String    — human-readable reason when denied
+        #   reasons: FailureReasons — structured reasons (not modelled here; omitted from the
+        #                         :AuthorizationResult fragment to avoid pulling that subtree).
+        # Reusable node type behind the schema's many `canXXX: AuthorizationResult` fields.
+        class AuthorizationResult < Logic::BaseModel
+          read_only!
+
+          passboolean :value
+          passthrough :message
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/contractor_entity/member_changes.rb

@@ -3,7 +3,13 @@ module Ecoportal
     class GraphQL
       module Base
         class ContractorEntity
+          # Convenience mutators over the read-model `associatedPeopleIds` / `leadContractorIds`
+          # arrays. They push/delete plain ids so that `Input::ContractorEntity::Update.from_model`
+          # can later emit the IdDiff (additions/removals) against `original_doc`.
           module MemberChanges
+            # Associates one or more people. When `lead: true`, also marks them as leads.
+            # @param values [Array<String, Hash, Person, Enumerable>] ids (or things resolvable to ids).
+            # @param lead [Boolean] whether the associated people are also lead contractors.
             def associate(*values, lead: false)
               ids = to_person_ids(*values)
 
@@ -15,7 +21,9 @@ module Ecoportal
               end
             end
 
-            def dissassociate(*values)
+            # Disassociates one or more people (also removing them as leads).
+            # @param values [Array<String, Hash, Person, Enumerable>] ids (or resolvable to ids).
+            def disassociate(*values)
               ids = to_person_ids(*values)
 
               associatedPeopleIds.tap do |associated|
@@ -23,7 +31,10 @@ module Ecoportal
                 associated.delete!(*ids)
               end
             end
+            # @deprecated Backwards-compatible alias for the original misspelling.
+            alias_method :dissassociate, :disassociate
 
+            # Marks one or more people as lead contractors (associating them if not already).
             def lead!(*values)
               ids = to_person_ids(*values)
 
@@ -33,6 +44,7 @@ module Ecoportal
               end
             end
 
+            # Removes one or more people from the lead contractors list.
             def unlead!(*values)
               ids = to_person_ids(*values)
 
@@ -44,7 +56,7 @@ module Ecoportal
             private
 
             def to_person_ids(*values)
-              to_person_id(values.flatten)
+              Array(to_person_id(values.flatten)).flatten.compact
             end
 
             def to_person_id(value)
@@ -54,9 +66,9 @@ module Ecoportal
               when Ecoportal::API::V1::Person
                 value.id
               when Hash
-                to_person_id(['id'])
-              when Enumarable
-                value.map {|val| to_person_id(val)}.compact
+                value['id'] || value[:id]
+              when Enumerable
+                value.map { |val| to_person_id(val) }.compact
               end
             end
           end

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

@@ -2,11 +2,19 @@ module Ecoportal
   module API
     class GraphQL
       module Base
+        # Verified against the live schema 2026-07-30: activeFileAttachment, activeName,
+        # activeVersion, archive, canDownload, canShow, draft, fileAttachments, fileSize, id,
+        # locations, name, otherTags, tags, token.
+        #
+        # ★ `activeVersionId` was declared here and does NOT exist on the type (it is
+        # `activeVersion`) — it always read nil. `otherTags` was missing, which matters because
+        # `UploadInput.otherTags` is the only way to tag a container.
         class FileContainer < Logic::BaseModel
-          passkey :id
-          passthrough :name, :activeName
-          passthrough :fileSize, :token, :activeVersionId
-          passarray :tags
+          passkey     :id
+          passthrough :name, :activeName, :activeVersion
+          passthrough :fileSize, :token
+          passboolean :draft
+          passarray   :tags, :otherTags
         end
       end
     end

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

@@ -8,6 +8,8 @@ module Ecoportal
           passkey :id
           passthrough :name
           passboolean :active
+          # Whether this classification was AI-generated (2026-07 schema).
+          passboolean :aiGenerated, read_only: true
         end
       end
     end

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

@@ -11,6 +11,9 @@ module Ecoportal
           passkey :id
           passthrough :name, :weight
           passboolean :archived, :published, :visitorManagementEnabled
+          # AI-generated structure support (2026-07 schema).
+          passthrough :aiPrompt, read_only: true
+          passboolean :generating, read_only: true
           embeds_one :updatedAt, klass: Base::DateTime
 
           embeds_many :drafts, klass: :draft_class, order_key: :createdAt

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

@@ -0,0 +1,25 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # Lightweight dashboard descriptor returned by the `dashboardSearch` connection.
+        # Read-only. For the full dashboard (components, filters, permissions) the
+        # `Dashboard` type is not yet modelled — see docs/worklog.md.
+        #
+        # Enum-valued fields are exposed as plain strings:
+        # - permissionType: 'GLOBAL' | 'RESTRICTED' | 'PRIVATE'
+        # - parentResourceType: DashboardParentResource (REGISTER, REPORTING, TASKS, ...)
+        class MinimalDashboard < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :name
+          passthrough :parentResource, :parentResourceId, :parentResourceType
+          passthrough :permissionType
+          passthrough :weight
+          passboolean :global
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,8 @@ module Ecoportal
           passkey :id
           passthrough :name, :companyName
           passthrough :logoUrl, read_only: true
+          # Whether contractor admins may add other contractor admins (2026-07 schema).
+          passboolean :allowContractorAdminsToAddAdmins, read_only: true
         end
       end
     end

data/lib/ecoportal/api/graphql/base/page/data_field/contractor_entities.rb

@@ -3,10 +3,13 @@ module Ecoportal::API::GraphQL::Base::Page
     # Contractor entity selector field.
     # Stores references to ContractorEntity records.
     class ContractorEntities < DataField
-      passarray :contractors # each: { id:, name: }
+      passarray :contractors # staged writes; the READ response uses `contractorEntities`
 
+      # Current contractor-entity ids. The GraphQL response carries them under
+      # `contractorEntities` (CommonPageUnion's contractorEntitiesField), NOT `contractors`
+      # — so read from there. After a contractor_entity_ids= write, prefer the staged value.
       def contractor_entity_ids
-        Array(contractors).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+        contractor_ids_from(doc)
       end
 
       def contractor_entity_ids=(ids)
@@ -18,11 +21,31 @@ module Ecoportal::API::GraphQL::Base::Page
         self.contractor_entity_ids = ids
       end
 
+      # Dirty only when the effective id SET actually changed — same phantom-dirty class as
+      # CrossReference (READ one key, WRITE another): the default leaf diff flags the field
+      # the moment the `contractors` key appears, even for a no-op restatement or a clear on
+      # an already-empty field.
+      def dirty?
+        contractor_ids_from(doc).sort != contractor_ids_from(original_doc).sort
+      end
+
       def as_input
         return nil unless dirty?
 
         { contractorEntities: { id: id, contractorEntityIds: contractor_entity_ids } }
       end
+
+      private
+
+      # Prefer the staged `contractors` (write shape), fall back to `contractorEntities`
+      # (read shape). Shape-agnostic for both `doc` and `original_doc`, so the comparison
+      # stays correct after `consolidate!` copies the staged shape into the baseline.
+      def contractor_ids_from(source_doc)
+        return [] unless source_doc
+
+        src = source_doc.key?('contractors') ? source_doc['contractors'] : source_doc['contractorEntities']
+        Array(src).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+      end
     end
   end
 end