rails_ai_admin 0.1.0

data/lib/rails_ai_admin/collections/contract.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Collections
+    module Contract
+      ACTIVE = %w[queued running].freeze
+      TERMINAL = %w[succeeded failed partially_succeeded cancelled reconciliation_required].freeze
+
+      def self.owned(context, ref, lock: false)
+        raise AccessDenied, "UNAUTHENTICATED" unless context.is_a?(Context)
+        raise AccessDenied unless ref.is_a?(String) && ref.match?(/\A[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\z/)
+        relation = lock ? OperationRun.lock : OperationRun.all
+        run = relation.where.not(selection_id: nil).find_by(id: ref, parent_run_id: nil, actor_ref: context.actor_ref, tenant_ref: context.tenant_ref)
+        raise AccessDenied unless run
+        raise AccessDenied, "APPROVAL_INVALIDATED" unless run.security_version == context.security_version
+        run
+      end
+
+      def self.definition(run)
+        resource = RailsAiAdmin.registry.fetch(run.resource_key)
+        definition = RailsAiAdmin.operation_registry.fetch(resource, run.operation)
+        unless definition.custom? && definition.scope == :collection && run.operation_version == Operations::RunnerFingerprint.call(resource, definition)
+          raise AccessDenied, "APPROVAL_INVALIDATED"
+        end
+        ensure_pool!(resource)
+        [ resource, definition ]
+      end
+
+      def self.ensure_outside_transaction!
+        raise ConfigurationError, "Collection admission, cancellation and worker steps must own their transaction" if OperationRun.connection.transaction_open?
+      end
+
+      def self.ensure_pool!(resource)
+        model = resource.model_class
+        unless [ OperationRun, AuditEvent, WorkItem, BatchItem, Selection, SelectionItem ].all? { |klass| klass.connection_pool.equal?(model.connection_pool) } &&
+            RecordVersion.supported?(model) && %w[SQLite PostgreSQL].include?(model.connection.adapter_name)
+          raise ConfigurationError, "Collection storage and domain must share one SQLite/PostgreSQL pool with lock_version or updated_at"
+        end
+      end
+
+      def self.verify_manifest!(run)
+        manifest = run.manifest_payload
+        unless manifest.is_a?(Array) && manifest.size.between?(1, Selections::Builder::LIMIT) && manifest.all? { |pair| pair.is_a?(Array) && pair.size == 2 && pair[0].is_a?(String) && pair[0].bytesize.between?(1, 150) && pair[1].is_a?(Integer) && pair[1] >= 0 } &&
+            manifest.map(&:first).uniq.size == manifest.size && manifest.sort_by(&:first) == manifest &&
+            InputSchema.digest(resource_version: run.manifest_resource_version, targets: manifest) == run.selection_digest
+          raise AccessDenied, "APPROVAL_INVALIDATED"
+        end
+        manifest
+      end
+
+      def self.approval_digest(run)
+        InputSchema.digest(actor: run.actor_ref, tenant: run.tenant_ref, epoch: run.security_version,
+          resource: run.resource_key, operation: run.operation, version: run.operation_version,
+          selection: run.selection_id, input_digest: run.input_digest, selection_digest: run.selection_digest,
+          deadline: run.execution_deadline)
+      end
+
+      def self.verify_approved!(run, definition, context)
+        verify_manifest!(run)
+        values = InputSchema.new(definition.handler_class.input).coerce(run.input_payload, time_zone: context.time_zone)
+        unless run.confirmed_at && run.approved_by_ref == run.actor_ref && run.approved_digest == approval_digest(run) &&
+            run.execution_deadline && values.valid? && InputSchema.digest(values.values) == run.input_digest
+          raise AccessDenied, "APPROVAL_INVALIDATED"
+        end
+      end
+
+      # Caller holds the parent lock. Each successful child updates its own receipt
+      # and these aggregate statuses inside that same business transaction.
+      def self.refresh!(run)
+        counts = BatchItem.where(parent_run_id: run.id).group(:status).count
+        raise ConfigurationError, "Collection item count changed" unless counts.values.sum == run.manifest_payload.size
+        status = if counts.fetch("running", 0) > 0
+          "running"
+        elsif counts.fetch("queued", 0) > 0
+          "queued"
+        elsif counts.fetch("succeeded", 0) == run.manifest_payload.size
+          "succeeded"
+        elsif counts.fetch("succeeded", 0) > 0
+          "partially_succeeded"
+        elsif counts.fetch("cancelled", 0) > 0
+          "cancelled"
+        else
+          "failed"
+        end
+        run.update!(status: status, completed_at: TERMINAL.include?(status) ? Time.current : nil)
+        status
+      end
+
+      def self.quarantine!(run, code)
+        BatchItem.where(parent_run_id: run.id, status: ACTIVE).update_all(status: "cancelled", last_code: code,
+          completed_at: Time.current, lease_owner: nil, lease_expires_at: nil)
+        run.update!(status: "reconciliation_required", completed_at: Time.current)
+      end
+
+      def self.stop_remaining!(run, code)
+        # A domain transaction holds this same parent lock. Once acquired, an
+        # uncommitted claimed item can be fenced without racing a business commit.
+        BatchItem.where(parent_run_id: run.id, status: ACTIVE).update_all(status: "cancelled", last_code: code,
+          completed_at: Time.current, lease_owner: nil, lease_expires_at: nil)
+        refresh!(run)
+      end
+
+      def self.contention?(error)
+        error.is_a?(ActiveRecord::Deadlocked) || error.is_a?(ActiveRecord::LockWaitTimeout) || error.is_a?(ActiveRecord::RecordNotUnique) ||
+          (defined?(SQLite3::BusyException) && error.cause.is_a?(SQLite3::BusyException))
+      end
+
+      def self.result(run, replayed: false)
+        Result.new(code: ACTIVE.include?(run.status) ? "QUEUED" : "OK", job_ref: run.id, status: run.status, replayed: replayed, warning: run.warning_code)
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/collections/dispatcher.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Collections
+    # Executes bounded, independently committed database items. A recurring host
+    # scan recovers queue loss and expired leases; no scheduler is installed.
+    class Dispatcher
+      def run(job_ref, limit: 100)
+        raise ArgumentError, "limit must be between 1 and 100" unless limit.is_a?(Integer) && (1..100).cover?(limit)
+        raise ConfigurationError, "Collection execution cannot run inside an existing transaction" if OperationRun.connection.transaction_open?
+        limit.times do
+          claim = claim_next(job_ref)
+          break unless claim
+          next if claim.is_a?(Result)
+          result = begin
+            Operations::Runner.new.execute_admitted(claim: claim)
+          rescue ConfigurationError, NameError
+            Operations::Result.new(code: "APPROVAL_INVALIDATED")
+          rescue StandardError
+            Operations::Result.new(code: "OPERATION_FAILED")
+          end
+          break if result.code == "FENCED"
+          break if !result.success? && !finish_rejected(claim, result)
+        end
+        parent = OperationRun.where.not(selection_id: nil).find_by(id: job_ref, parent_run_id: nil)
+        parent ? Contract.result(parent) : Result.new(code: "NOT_FOUND")
+      end
+
+      def scan_pending!(limit: 100, inline: false)
+        raise ArgumentError, "limit must be between 1 and 1000" unless limit.is_a?(Integer) && (1..1000).cover?(limit)
+        now = Time.current
+        queued = BatchItem.where(status: "queued").where("next_attempt_at IS NULL OR next_attempt_at <= ?", now)
+        stale = BatchItem.where(status: "running").where("lease_expires_at IS NULL OR lease_expires_at <= ?", now)
+        ids = queued.or(stale).distinct.limit(limit).pluck(:parent_run_id)
+        ids.count do |ref|
+          if inline
+            run(ref)
+            true
+          else
+            !!ExecutionJob.perform_later(ref)
+          end
+        end
+      end
+
+      # Exposed to trusted worker infrastructure for deterministic lease tests.
+      # Claiming grants no write permission; Runner checks the full binding again.
+      def claim_next(job_ref)
+        Contract.ensure_outside_transaction!
+        OperationRun.transaction(requires_new: true) do
+          parent = OperationRun.lock.where.not(selection_id: nil).find_by(id: job_ref, parent_run_id: nil)
+          next unless parent && Contract::ACTIVE.include?(parent.status)
+          begin
+            _resource, definition = Contract.definition(parent)
+            Contract.verify_manifest!(parent)
+          rescue AccessDenied, ConfigurationError, NameError
+            Contract.quarantine!(parent, "APPROVAL_INVALIDATED")
+            next
+          end
+          if parent.cancellation_requested_at || !parent.execution_deadline || parent.execution_deadline <= Time.current
+            Contract.stop_remaining!(parent, parent.cancellation_requested_at ? "CANCELLED" : "EXECUTION_EXPIRED")
+            next
+          end
+          now = Time.current
+          next if BatchItem.where(parent_run_id: parent.id, status: "running").where("lease_expires_at > ?", now).exists?
+          ready = BatchItem.where(parent_run_id: parent.id, status: "queued").where("next_attempt_at IS NULL OR next_attempt_at <= ?", now)
+          expired = BatchItem.where(parent_run_id: parent.id, status: "running").where("lease_expires_at IS NULL OR lease_expires_at <= ?", now)
+          item = ready.or(expired).order(:position).lock.first
+          next unless item
+          if item.attempts >= definition.handler_class.max_attempts
+            item.update!(status: "failed", last_code: "ATTEMPTS_EXHAUSTED", completed_at: now)
+            Contract.refresh!(parent)
+            next Result.new(code: "ATTEMPTS_EXHAUSTED", job_ref: parent.id, status: parent.status)
+          end
+          item.update!(status: "running", lease_owner: SecureRandom.uuid, generation: item.generation + 1,
+            attempts: item.attempts + 1, lease_expires_at: now + definition.handler_class.lease_duration, next_attempt_at: nil)
+          parent.update!(status: "running")
+          Claim.new(item)
+        end
+      rescue ActiveRecord::StatementInvalid => error
+        raise unless Contract.contention?(error)
+        nil
+      end
+
+      private
+
+      def finish_rejected(claim, result)
+        OperationRun.transaction(requires_new: true) do
+          parent = OperationRun.lock.find(claim.parent_ref)
+          item = BatchItem.lock.find(claim.item_ref)
+          next unless item.status == "running" && item.lease_owner == claim.owner && item.generation == claim.generation
+          # An expired response cannot finalize the old lease. The durable running
+          # item is left for the scanner to reclaim, without changing its receipt.
+          next unless item.lease_expires_at && item.lease_expires_at > Time.current
+          lease_deadline = item.lease_expires_at
+          finalized = if %w[APPROVAL_INVALIDATED AUTHORIZATION_REVOKED CANCELLED EXECUTION_EXPIRED].include?(result.code)
+            Contract.stop_remaining!(parent, result.code)
+          else
+            retryable = result.code == "OPERATION_FAILED" && item.attempts < current_attempt_limit(parent) && parent.execution_deadline > Time.current
+            item.update!(status: retryable ? "queued" : (result.code == "NOT_FOUND" ? "cancelled" : "failed"), last_code: result.code,
+              next_attempt_at: retryable ? Time.current + [ 2**item.attempts, 60 ].min : nil,
+              completed_at: retryable ? nil : Time.current)
+            AuditEvent.create!(actor_ref: parent.actor_ref, tenant_ref: parent.tenant_ref, resource_key: parent.resource_key,
+              operation: parent.operation, status: "rejected", code: result.code, correlation_ref: item.operation_run_id,
+              origin: parent.origin, changed_fields: [], created_at: Time.current)
+            Contract.refresh!(parent)
+          end
+          raise AccessDenied, "FENCED" unless lease_deadline > Time.current
+          finalized
+        end
+      rescue AccessDenied => error
+        raise unless error.code == "FENCED"
+        nil
+      rescue ActiveRecord::StatementInvalid => error
+        raise unless Contract.contention?(error)
+        nil
+      end
+
+      def current_attempt_limit(parent)
+        _resource, definition = Contract.definition(parent)
+        definition.handler_class.max_attempts
+      rescue AccessDenied
+        0
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/collections/queries.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Collections
+    class Queries
+      Entry = Data.define(:record_id, :label, :status, :code, :audit_ref, :warning, :work_statuses)
+      # waiting_since: when the oldest still-queued item of an active run was
+      # queued, so a page can say that nothing has picked it up (RAA-020).
+      Snapshot = Data.define(:job_ref, :resource_key, :operation, :description, :status, :counts, :entries, :hidden_count, :can_cancel, :warning, :waiting_since)
+
+      def fetch(context:, job_ref:, summary: false)
+        ActiveRecord::Base.while_preventing_writes do
+          parent = Contract.owned(context, job_ref)
+          resource, definition = Contract.definition(parent)
+          access = Authorization::Access.new(context, resource)
+          access.authorize_receipt!(parent.operation, nil)
+          Contract.verify_manifest!(parent)
+          Contract.verify_approved!(parent, definition, context) if parent.approved_digest
+          items = BatchItem.where(parent_run_id: parent.id).order(:position).limit(Selections::Builder::LIMIT + 1).to_a
+          if parent.approved_digest && items.size != parent.manifest_payload.size
+            raise ConfigurationError, "Collection result manifest is inconsistent"
+          end
+          counts = items.group_by(&:status).transform_values(&:size).freeze
+          entries = summary ? [] : items.filter_map { |item| entry(access, parent, item) }
+          cancellable = begin
+            access.authorize_cancel!(parent.operation)
+            parent.status == "proposed" || Contract::ACTIVE.include?(parent.status)
+          rescue AccessDenied
+            false
+          end
+          waiting = Contract::ACTIVE.include?(parent.status) && items.none? { |item| item.status == "running" } ?
+            items.select { |item| item.status == "queued" }.map(&:created_at).compact.min : nil
+          Snapshot.new(parent.id, resource.key.to_s, parent.operation, definition.description, parent.status, counts,
+            entries.freeze, summary ? 0 : items.size - entries.size, cancellable, parent.warning_code, waiting)
+        end
+      rescue StandardError => error
+        raise if error.is_a?(AccessDenied) || error.is_a?(ConfigurationError)
+        raise ConfigurationError, "Collection result cannot be projected safely", cause: nil
+      end
+
+      def recent(context:)
+        raise AccessDenied, "UNAUTHENTICATED" unless context.is_a?(Context)
+        refs = OperationRun.where(actor_ref: context.actor_ref, tenant_ref: context.tenant_ref, security_version: context.security_version,
+          parent_run_id: nil).where.not(selection_id: nil).where.not(status: "proposed").order(created_at: :desc, id: :desc).limit(50).pluck(:id)
+        refs.filter_map do |ref|
+          fetch(context: context, job_ref: ref, summary: true)
+        rescue AccessDenied
+          nil
+        end
+      end
+
+      private
+
+      def entry(access, parent, item)
+        unless parent.manifest_payload[item.position] == [ item.target_id, item.expected_version ]
+          raise ConfigurationError, "Collection item identity changed"
+        end
+        record = access.find!(item.target_id)
+        access.authorize_receipt!(parent.operation, record)
+        label = access.record_label(record)
+        child = OperationRun.find_by!(id: item.operation_run_id, parent_run_id: parent.id)
+        unless child.target_id == item.target_id && child.expected_version == item.expected_version &&
+            child.resource_key == parent.resource_key && child.operation == parent.operation && child.input_digest == parent.input_digest &&
+            child.actor_ref == parent.actor_ref && child.tenant_ref == parent.tenant_ref && child.operation_version == parent.operation_version
+          raise ConfigurationError, "Collection child identity changed"
+        end
+        work = WorkItem.where(operation_run_id: child.id).filter_map do |work_item|
+          access.authorize_delivery!(parent.operation, work_item.kind, record)
+          work_item.status
+        rescue AccessDenied
+          nil
+        end.tally.freeze
+        Entry.new(record.id.to_s, label, item.status, item.last_code, child.audit_event_id, child.warning_code, work)
+      rescue AccessDenied
+        nil
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/collections/result.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Collections
+    class Result
+      attr_reader :code, :job_ref, :status, :errors, :replayed, :warning
+      def initialize(code:, job_ref: nil, status: "rejected", errors: {}, replayed: false, warning: nil)
+        @code, @job_ref, @status, @errors, @replayed, @warning = code, job_ref, status, errors.freeze, replayed, warning
+        freeze
+      end
+      def accepted? = job_ref.present? && %w[QUEUED OK].include?(code)
+      def success? = status == "succeeded"
+    end
+  end
+end

data/lib/rails_ai_admin/collections/runner.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Collections
+    # One parent owns approval. Per-target child intents are created only at
+    # admission, and can execute solely through an admitted worker lease.
+    class Runner
+      PREFLIGHT_BUDGET = 30
+      Target = Data.define(:id, :label, :changes)
+      Proposal = Data.define(:intent, :values, :targets)
+      class Rejected < StandardError
+        attr_reader :result
+        def initialize(code, errors = {})
+          @result = Result.new(code: code, errors: errors)
+          super(code)
+        end
+      end
+
+      def preflight(context:, resource:, operation:, selection_ref:, input:, origin: :ui)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + PREFLIGHT_BUDGET
+        raise ConfigurationError, "Unsupported origin" unless Operations::Runner::ORIGINS.include?(origin.to_s)
+        definition = RailsAiAdmin.operation_registry.fetch(resource, operation)
+        raise ConfigurationError, "Expected a collection operation" unless definition.custom? && definition.scope == :collection
+        Contract.ensure_pool!(resource)
+        selection = Selections::Builder.new.revalidate(context: context, selection_ref: selection_ref, resource: resource)
+        values = collection_input(context, resource, definition, input)
+        targets = previews(context, resource, definition, selection, values, deadline: deadline)
+        raise Rejected.new("VALIDATION_FAILED", "base" => [ "preview is too large" ]) if JSON.generate(targets.map(&:changes)).bytesize > 262_144
+        source = Selection.find(selection.selection_ref)
+        manifest = selection.targets.map { |target| [ target.id, target.expected_version ] }
+        payload = wire(values)
+        raise Rejected.new("VALIDATION_FAILED", "base" => [ "input is too large" ]) if JSON.generate(payload).bytesize > 4096
+        intent = OperationRun.create!(id: SecureRandom.uuid, actor_ref: context.actor_ref, tenant_ref: context.tenant_ref,
+          security_version: context.security_version, resource_key: resource.key.to_s, operation: definition.key,
+          operation_version: Operations::RunnerFingerprint.call(resource, definition), selection_id: selection.selection_ref,
+          selection_digest: selection.manifest_digest, manifest_resource_version: source.resource_version,
+          manifest_payload: manifest, input_payload: payload, input_digest: InputSchema.digest(values), origin: origin.to_s,
+          expires_at: Time.current + RailsAiAdmin.configuration.intent_ttl)
+        Proposal.new(intent, values, targets.freeze)
+      rescue Rejected => error
+        error.result
+      rescue AccessDenied => error
+        Result.new(code: error.code)
+      rescue StandardError => error
+        raise if error.is_a?(ConfigurationError)
+        Result.new(code: Contract.contention?(error) ? "CONFLICT" : "OPERATION_FAILED")
+      end
+
+      def admit(context:, intent_ref:, input:, human_confirmed: false, binding: nil)
+        admitted = false
+        Contract.ensure_outside_transaction!
+        result = OperationRun.transaction(requires_new: true) do
+          run = Contract.owned(context, intent_ref, lock: true)
+          resource, definition = Contract.definition(run)
+          verify_binding!(run, binding) if binding
+          Contract.verify_manifest!(run)
+          if run.status != "proposed"
+            Authorization::Access.new(context, resource).authorize_receipt!(run.operation, nil)
+            raise Rejected.new("CONFLICT") unless Contract::ACTIVE.include?(run.status) || (Contract::TERMINAL.include?(run.status) && run.approved_digest)
+            Contract.verify_approved!(run, definition, context)
+            verify_input!(run, definition, context, input, replay: true)
+            next Contract.result(run, replayed: true)
+          end
+          raise Rejected.new("APPROVAL_EXPIRED") unless run.expires_at > Time.current
+          raise Rejected.new("APPROVAL_REQUIRED") unless human_confirmed == true
+          values = collection_input(context, resource, definition, input)
+          raise Rejected.new("APPROVAL_INVALIDATED") unless InputSchema.digest(values) == run.input_digest
+          access = Authorization::Access.new(context, resource)
+          selection = Selections::Builder.new.validate_for_admission(context: context, selection_ref: run.selection_id, resource: resource, manifest_digest: run.selection_digest) do |record|
+            access.authorize!(definition.key, record)
+            current = InputSchema.new(definition.fields(access, record)).coerce(wire(values), time_zone: context.time_zone)
+            raise Rejected.new("APPROVAL_INVALIDATED") unless current.valid? && InputSchema.digest(current.values) == run.input_digest
+          end
+          raise Rejected.new("APPROVAL_INVALIDATED") unless selection.targets.map { |target| [ target.id, target.expected_version ] } == run.manifest_payload
+          deadline = Time.current + definition.handler_class.execution_window
+          source_items = SelectionItem.where(selection_id: run.selection_id).order(:position).limit(Selections::Builder::LIMIT + 1).to_a
+          unless source_items.map { |item| [ item.target_id, item.expected_version ] } == run.manifest_payload && source_items.map(&:position) == (0...source_items.size).to_a
+            raise Rejected.new("APPROVAL_INVALIDATED")
+          end
+          now = Time.current
+          children, items = [], []
+          source_items.each do |item|
+            id = SecureRandom.uuid
+            children << { id: id, parent_run_id: run.id, actor_ref: run.actor_ref, tenant_ref: run.tenant_ref,
+              security_version: run.security_version, resource_key: run.resource_key, operation: run.operation,
+              operation_version: run.operation_version, target_id: item.target_id, expected_version: item.expected_version,
+              input_digest: run.input_digest, origin: run.origin, expires_at: deadline, created_at: now, updated_at: now }
+            items << { id: SecureRandom.uuid, parent_run_id: run.id, operation_run_id: id, selection_item_id: item.id,
+              target_id: item.target_id, expected_version: item.expected_version, position: item.position, created_at: now, updated_at: now }
+          end
+          OperationRun.insert_all!(children)
+          BatchItem.insert_all!(items)
+          audit = AuditEvent.create!(actor_ref: run.actor_ref, tenant_ref: run.tenant_ref, resource_key: run.resource_key,
+            operation: run.operation, status: "admitted", code: "QUEUED", correlation_ref: run.id, origin: run.origin, changed_fields: [], created_at: now)
+          run.execution_deadline = deadline
+          run.update!(status: "queued", audit_event_id: audit.id, approved_by_ref: context.actor_ref,
+            approved_digest: Contract.approval_digest(run), confirmed_at: now, execution_deadline: deadline)
+          admitted = true
+          Contract.result(run)
+        end
+        result || Result.new(code: "CONFLICT")
+      rescue Rejected => error
+        error.result
+      rescue AccessDenied => error
+        Result.new(code: error.code)
+      rescue StandardError => error
+        if admitted && !OperationRun.connection.transaction_open?
+          begin
+            committed = OperationRun.find_by(id: intent_ref, actor_ref: context.actor_ref, tenant_ref: context.tenant_ref)
+          rescue ActiveRecord::ActiveRecordError
+            return Result.new(code: "OUTCOME_UNKNOWN", job_ref: intent_ref, status: "unknown")
+          end
+          if committed && committed.approved_digest && committed.status != "proposed"
+            return Contract.result(committed)
+          end
+        end
+        raise if error.is_a?(ConfigurationError)
+        Result.new(code: Contract.contention?(error) ? "CONFLICT" : "OPERATION_FAILED")
+      end
+
+      def cancel(context:, job_ref:)
+        cancelling = false
+        Contract.ensure_outside_transaction!
+        OperationRun.transaction(requires_new: true) do
+          run = Contract.owned(context, job_ref, lock: true)
+          resource, = Contract.definition(run)
+          Authorization::Access.new(context, resource).authorize_cancel!(run.operation)
+          changed = run.status == "proposed" || Contract::ACTIVE.include?(run.status)
+          if run.status == "proposed"
+            run.update!(status: "cancelled", cancellation_requested_at: Time.current, completed_at: Time.current)
+          elsif Contract::ACTIVE.include?(run.status)
+            run.update!(cancellation_requested_at: Time.current)
+            Contract.stop_remaining!(run, "CANCELLED")
+          end
+          if changed
+            AuditEvent.create!(actor_ref: context.actor_ref, tenant_ref: context.tenant_ref, resource_key: run.resource_key,
+              operation: run.operation, status: "cancelled", code: "CANCELLED", correlation_ref: run.id, origin: "ui", changed_fields: [], created_at: Time.current)
+          end
+          cancelling = changed
+          Result.new(code: "CANCELLED", job_ref: run.id, status: run.status)
+        end
+      rescue AccessDenied => error
+        Result.new(code: error.code)
+      rescue StandardError => error
+        if cancelling && !OperationRun.connection.transaction_open?
+          begin
+            committed = OperationRun.find_by(id: job_ref, actor_ref: context.actor_ref, tenant_ref: context.tenant_ref)
+          rescue ActiveRecord::ActiveRecordError
+            return Result.new(code: "OUTCOME_UNKNOWN", job_ref: job_ref, status: "unknown")
+          end
+          if committed&.cancellation_requested_at
+            return Result.new(code: "CANCELLED", job_ref: committed.id, status: committed.status)
+          end
+        end
+        raise if error.is_a?(ConfigurationError)
+        Result.new(code: Contract.contention?(error) ? "CONFLICT" : "OPERATION_FAILED")
+      end
+
+      private
+
+      def verify_binding!(run, binding)
+        expected = { resource_key: run.resource_key, operation: run.operation, selection_id: run.selection_id }
+        raise AccessDenied unless binding.transform_values { |value| value&.to_s } == expected
+      end
+
+      def verify_input!(run, definition, context, input, replay: false)
+        coercion = InputSchema.new(definition.handler_class.input).coerce(input, time_zone: context.time_zone)
+        raise Rejected.new(replay ? "IDEMPOTENCY_CONFLICT" : "APPROVAL_INVALIDATED") unless coercion.valid? && InputSchema.digest(coercion.values) == run.input_digest
+      end
+
+      def collection_input(context, resource, definition, input)
+        ActiveRecord::Base.while_preventing_writes do
+          access = Authorization::Access.new(context, resource)
+          access.authorize!(definition.key)
+          coercion = InputSchema.new(definition.fields(access, nil)).coerce(input, time_zone: context.time_zone)
+          raise Rejected.new("VALIDATION_FAILED", coercion.errors) unless coercion.valid?
+          coercion.values
+        end
+      rescue ActiveRecord::ReadOnlyError
+        raise ConfigurationError, "Collection input resolution must be read-only", cause: nil
+      end
+
+      def previews(context, resource, definition, selection, values, deadline:)
+        runner = Operations::Runner.new
+        selection.targets.map do |target|
+          raise Rejected.new("TIMEOUT") if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          preview = runner.preview(context: context, resource: resource, operation: definition.key,
+            target_id: target.id, expected_version: target.expected_version, input: wire(values))
+          raise Rejected.new(preview.code, preview.errors) if preview.is_a?(Operations::Result)
+          raise Rejected.new("TIMEOUT") if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          raise Rejected.new("APPROVAL_INVALIDATED") unless InputSchema.digest(preview.values) == InputSchema.digest(values)
+          Target.new(target.id, target.label, preview.changes)
+        end
+      end
+
+      def wire(values)
+        values.transform_values do |value|
+          case value
+          when BigDecimal then value.to_s("F")
+          when Time, ActiveSupport::TimeWithZone then value.utc.iso8601(6)
+          when Date then value.iso8601
+          else value
+          end
+        end
+      end
+    end
+  end
+end