rails_ai_admin 0.1.0

data/lib/rails_ai_admin/authorization/access.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Authorization
+    # Intersects host decisions with declared exposure on every use.
+    class Access
+      attr_reader :context, :resource
+
+      def initialize(context, resource)
+        raise AccessDenied, "UNAUTHENTICATED" unless context.is_a?(Context)
+        @context, @resource = context, resource
+        @adapter = RailsAiAdmin.configuration.authorization_adapter.constantize.new
+      end
+
+      def authorize!(action, record = nil)
+        raise AccessDenied unless resource.action_enabled?(action) && @adapter.allowed?(context: context, action: action.to_sym, resource: resource, record: record) == true
+        true
+      end
+
+      def relation
+        relation = @adapter.scope(context: context, resource: resource, relation: resource.model_class.all)
+        unless relation.is_a?(ActiveRecord::Relation) && relation.klass == resource.model_class
+          raise ConfigurationError, "Policy scope must return the resource's ActiveRecord relation"
+        end
+        if relation.limit_value || relation.offset_value || relation.select_values.any? || relation.group_values.any? || !relation.having_clause.empty? || !relation.from_clause.empty?
+          raise ConfigurationError, "Policy scope must be a complete filter relation without limit, offset, select, group, having or from"
+        end
+        relation
+      end
+
+      def find!(id, action: :show, lock: false)
+        scoped = relation
+        scoped = scoped.lock if lock
+        record = scoped.find(id)
+        authorize!(action, record)
+        record
+      rescue ActiveRecord::RecordNotFound
+        raise AccessDenied
+      end
+
+      # "1abc", "01" and " 1" would otherwise be cast to record 1 (RAA-022).
+      # Pages address a record only by the primary key's canonical text; the
+      # trusted Runner API still canonicalizes through the scoped lookup.
+      def canonical_id?(id)
+        return id.positive? if id.is_a?(Integer)
+        return false unless id.is_a?(String) && id.valid_encoding? && id.bytesize.between?(1, 150) && !id.match?(/[[:cntrl:]]|[[:space:]]/)
+        case resource.model_class.type_for_attribute(resource.model_class.primary_key).type
+        when :integer then id.match?(/\A[1-9][0-9]{0,18}\z/)
+        when :uuid then id.match?(/\A[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}\z/)
+        else true
+        end
+      end
+
+      VIEWS = %i[index show create edit].freeze
+
+      def fields(action, record = nil, operation: nil, view: nil)
+        view = write_view(operation, view) if action == :write
+        granted = permission_fields(action, record, operation: operation, view: view)
+        action == :read && view ? granted.select { |field| field.visible_on?(view) } : granted
+      end
+
+      # only: optional field names to compute (for example index columns plus the
+      # title); it can narrow but never add to the granted, visible fields.
+      def project(record, view: nil, only: nil)
+        authorize!(:show, record)
+        granted = permission_fields(:read, record, view: view)
+        visible = view ? granted.select { |field| field.visible_on?(view) } : granted
+        visible = visible.select { |field| only.include?(field.name) } if only
+        Fields::Projection.new(self, record, granted).values(fields: visible)
+      end
+
+      # Declared named scopes intersected with the current independent grant, in
+      # declaration order. This performs no domain query.
+      def named_scopes
+        declared = resource.scopes
+        return [] if declared.empty?
+        names = @adapter.respond_to?(:named_scopes) ? @adapter.named_scopes(context: context, resource: resource) : []
+        unless names.is_a?(Array) && names.all? { |name| name.is_a?(String) || name.is_a?(Symbol) }
+          raise ConfigurationError, "Named scope grants must be an array of names"
+        end
+        names = names.map(&:to_sym)
+        declared.select { |definition| names.include?(definition.name) }
+      end
+
+      def authorize_selection!
+        authorize!(:index)
+        allowed = @adapter.respond_to?(:select_records?) && @adapter.select_records?(context: context, resource: resource) == true
+        raise AccessDenied unless allowed
+        true
+      end
+
+      # The model may see this resource only with the independent assistant
+      # grant plus the ordinary index grant; tools still apply every read grant.
+      def authorize_assistant!
+        authorize!(:index)
+        allowed = @adapter.respond_to?(:assistant?) && @adapter.assistant?(context: context, resource: resource) == true
+        raise AccessDenied unless allowed
+        true
+      end
+
+      # Scalar declarations cannot turn arbitrary model methods into read actions.
+      # Host overrides of real attribute getters remain trusted application code.
+      def read_value(record, field, view: nil)
+        unless resource.fields.any? { |candidate| candidate.equal?(field) }
+          raise ConfigurationError, "Read fields must belong to the current resource"
+        end
+        authorize!(:show, record)
+        granted = permission_fields(:read, record, view: view)
+        raise AccessDenied if view && !field.visible_on?(view)
+        Fields::Projection.new(self, record, granted).value(field)
+      end
+
+      def read_attribute(record, field)
+        raise AccessDenied if field.hidden? || field.scalar_type == :password
+        raise ConfigurationError, "Computed fields do not invoke model methods" if field.virtual?
+        return read_file(record, field) if field.scalar_type == :file
+        return read_files(record, field) if field.scalar_type == :files
+        return read_rich_text(record, field) if field.scalar_type == :rich_text
+        return read_references(record, field) if field.scalar_type == :references
+        name = field.column
+        primary_key = record.class.primary_key
+        id_alias = name == "id" && primary_key.is_a?(String) && record.has_attribute?(primary_key)
+        unless record.has_attribute?(name) || id_alias
+          raise ConfigurationError, "Scalar fields must name model attributes"
+        end
+        value = ActiveRecord::Base.while_preventing_writes { record.public_send(name) }
+        # References travel as opaque key text, matching their input contract.
+        field.scalar_type == :belongs_to && !value.nil? ? value.to_s : value
+      rescue ActiveRecord::ReadOnlyError
+        raise ConfigurationError, "Scalar attribute getters must not write", cause: nil
+      end
+
+      # Shared title contract for native pages, fixed selections and job entries.
+      def record_label(record, values: nil, view: :show)
+        fallback = "Record ##{record.id}"
+        authorize!(:show, record)
+        field = fields(:read, record, view: view).find { |candidate| candidate.name == resource.title }
+        return fallback unless field
+        return fallback if values && !values.key?(field.name.to_s)
+        value = values ? values.fetch(field.name.to_s) : read_value(record, field, view: view)
+        field.format(value, time_zone: context.time_zone).truncate(120)
+      rescue AccessDenied
+        fallback
+      end
+
+      def operation_fields(operation, record = nil)
+        definition = RailsAiAdmin.operation_registry.fetch(resource, operation)
+        return [] unless definition.custom?
+        names = @adapter.respond_to?(:operation_fields) ? @adapter.operation_fields(context: context, resource: resource, operation: operation.to_sym, record: record) : []
+        raise ConfigurationError, "Operation fields must be an array" unless names.is_a?(Array)
+        names = names.map(&:to_sym)
+        definition.handler_class.input.select { |field| names.include?(field.name) }
+      end
+
+      def authorize_export!
+        authorize!(:index)
+        allowed = @adapter.respond_to?(:export_records?) && @adapter.export_records?(context: context, resource: resource) == true
+        raise AccessDenied unless allowed
+        true
+      end
+
+      def authorize_import!
+        authorize!(:create, relation.new)
+        allowed = @adapter.respond_to?(:import_records?) && @adapter.import_records?(context: context, resource: resource) == true
+        raise AccessDenied unless allowed
+        true
+      end
+
+      def authorize_audit_log!
+        allowed = @adapter.respond_to?(:view_audit_log?) && @adapter.view_audit_log?(context: context, resource: resource) == true
+        raise AccessDenied unless allowed
+        true
+      end
+
+      def authorize_history!(record)
+        authorize!(:show, record)
+        allowed = @adapter.respond_to?(:view_history?) && @adapter.view_history?(context: context, resource: resource, record: record) == true
+        raise AccessDenied unless allowed
+        true
+      end
+
+      def authorize_delivery!(operation, work_kind, record)
+        allowed = @adapter.respond_to?(:deliver_work?) && @adapter.deliver_work?(context: context, resource: resource,
+          operation: operation.to_sym, work_kind: work_kind, record: record) == true
+        raise AccessDenied unless allowed
+        true
+      end
+
+      def authorize_cancel!(operation)
+        allowed = @adapter.respond_to?(:cancel_operation?) && @adapter.cancel_operation?(context: context, resource: resource, operation: operation.to_sym) == true
+        raise AccessDenied unless allowed
+        true
+      end
+
+      def authorize_receipt!(operation, record)
+        allowed = @adapter.respond_to?(:read_operation_receipt?) && @adapter.read_operation_receipt?(context: context,
+          resource: resource, operation: operation.to_sym, record: record) == true
+        raise AccessDenied unless allowed
+        true
+      end
+      # The saved attachment rows of a files field, oldest first. Pending
+      # attachments of an unsaved change are not included.
+      def stored_attachments(record, field)
+        attachment(record, field)
+        ::ActiveStorage::Attachment.where(record_type: record.class.polymorphic_name, record_id: record.id, name: field.column).order(:id)
+      end
+
+      # The Active Storage proxy for a file (has_one_attached) or files
+      # (has_many_attached) field.
+      def attachment(record, field)
+        macro = field.scalar_type == :files ? :has_many_attached : :has_one_attached
+        reflection = record.class.respond_to?(:reflect_on_attachment) && record.class.reflect_on_attachment(field.column)
+        raise ConfigurationError, "#{field.scalar_type} fields must name a #{macro} attachment" unless reflection && reflection.macro == macro
+        ActiveRecord::Base.while_preventing_writes { record.public_send(field.column) }
+      end
+
+      private
+
+      # The stored Action Text HTML, or nil. Pages sanitize it when they show it.
+      def read_rich_text(record, field)
+        unless record.class.reflect_on_association("rich_text_#{field.column}")
+          raise ConfigurationError, "rich_text fields must name a has_rich_text attribute"
+        end
+        content = ActiveRecord::Base.while_preventing_writes { record.public_send(field.column)&.body }
+        html = content&.to_html.to_s
+        html.match?(Field::BLANK) ? nil : String.new(html)
+      end
+
+      # The associated keys as sorted text. Targets the actor cannot see stay
+      # keys; pages label them through the target's own grants.
+      def read_references(record, field)
+        reflection = record.class.reflect_on_association(field.name)
+        unless reflection&.collection? && record.respond_to?(field.column)
+          raise ConfigurationError, "references fields must name a has_many or has_and_belongs_to_many association"
+        end
+        ids = ActiveRecord::Base.while_preventing_writes { record.public_send(field.column) }
+        ids.map { |id| id.to_s.freeze }.uniq.sort.freeze
+      end
+
+      # At most 100 files, oldest first, each with its attachment id.
+      def read_files(record, field)
+        attachments = stored_attachments(record, field).includes(:blob).limit(Field::MAX_REFERENCES).to_a
+        attachments.map { |item| Fields::FileValue.from(item.blob, id: item.id) }.freeze
+      end
+
+      def read_file(record, field)
+        attached = attachment(record, field)
+        attached.attached? ? Fields::FileValue.from(attached.blob) : nil
+      end
+
+      def write_view(operation, view)
+        expected = operation.to_sym == :create ? :create : :edit if operation
+        expected ||= :edit
+        raise ConfigurationError, "Write presentation must match its lifecycle" if view && view != expected
+        expected
+      end
+
+      def permission_fields(action, record, operation: nil, view: nil)
+        raise ConfigurationError, "Unknown presentation view" if view && !VIEWS.include?(view)
+        names = @adapter.fields(context: context, resource: resource, action: action, record: record)
+        unless names.is_a?(Array) && names.all? { |name| name.is_a?(String) || name.is_a?(Symbol) }
+          raise ConfigurationError, "Policy fields must be an array of names"
+        end
+        names = names.map(&:to_sym)
+        selected = resource.fields.select do |field|
+          !field.hidden? && names.include?(field.name) &&
+            # A password is write-only: no read grant can reveal it.
+            (action == :write || field.scalar_type != :password) &&
+            (action != :write || field.name.to_s != resource.model_class.primary_key) &&
+            (action != :write || field.writable?(operation || :update)) &&
+            (action != :search || !field.virtual? && field.options[:searchable]) &&
+            (action != :sort || !field.virtual? && field.options[:sortable]) &&
+            (action != :filter || !field.virtual? && field.filter_operators.any?)
+        end
+        mask = presentation_mask(record, view) if view
+        selected = selected.select { |field| mask.include?(field.name) } if mask
+        action == :read ? Fields::DependencyGraph.readable(selected) : selected
+      end
+
+      def presentation_mask(record, view)
+        return unless @adapter.respond_to?(:presentation_fields, true)
+        raise ConfigurationError, "Presentation policy must be public" unless @adapter.respond_to?(:presentation_fields)
+        names = ActiveRecord::Base.while_preventing_writes { @adapter.presentation_fields(context: context, resource: resource, view: view, record: record) }
+        return if names.nil?
+        unless names.is_a?(Array) && names.all? { |name| name.is_a?(String) || name.is_a?(Symbol) }
+          raise ConfigurationError, "Presentation policy must return nil or field names"
+        end
+        names.map(&:to_sym)
+      rescue ConfigurationError
+        raise
+      rescue StandardError
+        raise ConfigurationError, "Presentation policy failed", cause: nil
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/authorization/adapter.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Authorization
+    # Default-deny policy interface. Hosts explicitly implement every permission.
+    class Adapter
+      def scope(context:, resource:, relation:)
+        relation.none
+      end
+
+      def allowed?(context:, action:, resource:, record: nil)
+        false
+      end
+
+      # action is :read, :write, :search, :sort or :filter; no implicit grants.
+      # Filtering reveals values through membership, so it is never implied by read.
+      def fields(context:, resource:, action:, record: nil)
+        []
+      end
+
+      # Optional per-view narrowing, never a replacement for read/write grants.
+      # nil adds no restriction; [] hides every field in that view.
+      def presentation_fields(context:, resource:, view:, record: nil)
+        nil
+      end
+
+      # Custom operation inputs are independent of ordinary attribute write grants.
+      def operation_fields(context:, resource:, operation:, record: nil)
+        []
+      end
+
+      # Delivery authorizes a committed fact, not re-execution of its command.
+      def deliver_work?(context:, resource:, operation:, work_kind:, record:)
+        false
+      end
+
+      def read_operation_receipt?(context:, resource:, operation:, record:)
+        false
+      end
+
+      def cancel_operation?(context:, resource:, operation:)
+        false
+      end
+
+      # Named list scopes (declared tabs) this actor may use. A scope predicate can
+      # reveal facts about fields the actor cannot read, so it is granted apart
+      # from index/read/search/sort.
+      def named_scopes(context:, resource:)
+        []
+      end
+
+      # Capturing/viewing a fixed selection is independent of list/read/write.
+      def select_records?(context:, resource:)
+        false
+      end
+
+      # Exposes this resource to the admin assistant's tools. Human read grants
+      # still apply to every tool call; this grant only decides whether the
+      # model may see the resource at all. The assistant is available to an
+      # actor when at least one resource grants it.
+      def assistant?(context:, resource:)
+        false
+      end
+
+      # Downloads the current list as CSV. Rows, columns and values still come
+      # from the index, show and read grants; this grant only adds the button.
+      def export_records?(context:, resource:)
+        false
+      end
+
+      # Creates records from an uploaded CSV file. Each row still needs the
+      # create grant, write field grants and validations.
+      def import_records?(context:, resource:)
+        false
+      end
+
+      # Lists this resource's audit events on the audit log page, across
+      # records and actors of the current tenant. Field names still follow the
+      # read and write grants.
+      def view_audit_log?(context:, resource:)
+        false
+      end
+
+      # Shows a record's change history (who changed it, when, which fields).
+      # Field names are filtered to the actor's current read and write grants;
+      # this grant only decides whether the page exists for the record.
+      def view_history?(context:, resource:, record:)
+        false
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/authorization/pundit_adapter.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Authorization
+    # Optional Pundit integration using a separate explicit policy per resource.
+    # The policy receives the complete admin Context as its user argument.
+    class PunditAdapter < Adapter
+      ACTIONS = %i[index show create update destroy].freeze
+      FIELD_METHODS = { read: :readable_fields, write: :writable_fields,
+        search: :searchable_fields, sort: :sortable_fields, filter: :filterable_fields }.freeze
+
+      def initialize
+        require "pundit"
+        unless Gem::Requirement.new(">= 2.5", "< 3").satisfied_by?(Gem.loaded_specs.fetch("pundit").version)
+          raise ConfigurationError, "PunditAdapter requires pundit >= 2.5 and < 3"
+        end
+      rescue LoadError
+        raise ConfigurationError, "Add pundit >= 2.5 and < 3 to the host bundle", cause: nil
+      end
+
+      def scope(context:, resource:, relation:)
+        klass = policy_class(resource)
+        scope = klass && scope_class(klass)
+        return relation.none unless scope
+        # Pundit's documented explicit Scope constructor/resolve contract avoids
+        # guessing a model policy, which would merge resource-alias authority.
+        scope.new(context, relation).resolve
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def allowed?(context:, action:, resource:, record: nil)
+        return false unless ACTIONS.include?(action.to_sym) || resource.operation_declarations.key?(action.to_sym)
+        klass = policy_class(resource)
+        target = record || (action.to_sym == :create ? scope(context: context, resource: resource, relation: resource.model_class.all).new : resource.model_class)
+        return false unless klass && klass.new(context, target).respond_to?("#{action}?")
+        Pundit.authorize(context, target, "#{action}?", policy_class: klass)
+        true
+      rescue Pundit::NotAuthorizedError
+        false
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def fields(context:, resource:, action:, record: nil)
+        method = FIELD_METHODS[action.to_sym]
+        klass = policy_class(resource)
+        return [] unless method && klass
+        policy = klass.new(context, record || resource.model_class)
+        policy.respond_to?(method) ? policy.public_send(method) : []
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def presentation_fields(context:, resource:, view:, record: nil)
+        klass = policy_class(resource)
+        return [] unless klass
+        policy = klass.new(context, record || resource.model_class)
+        return unless policy.respond_to?(:presentation_fields, true)
+        raise ConfigurationError, "Presentation policy must be public" unless policy.respond_to?(:presentation_fields)
+        policy.presentation_fields(view)
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      # Reports whether an explicit policy and its owned/inherited Scope exist.
+      # This checks metadata only; it does not attest any authorization decision.
+      def configured?(resource)
+        klass = policy_class(resource)
+        !!(klass && scope_class(klass))
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def operation_fields(context:, resource:, operation:, record: nil)
+        klass = policy_class(resource)
+        return [] unless klass
+        policy = klass.new(context, record || resource.model_class)
+        policy.respond_to?(:permitted_operation_fields) ? policy.permitted_operation_fields(operation.to_sym) : []
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def deliver_work?(context:, resource:, operation:, work_kind:, record:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, record)
+        policy.respond_to?(:deliver_operation_work?) && policy.deliver_operation_work?(operation.to_sym, work_kind.to_s) == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def read_operation_receipt?(context:, resource:, operation:, record:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, record || resource.model_class)
+        policy.respond_to?(:read_operation_receipt?) && policy.read_operation_receipt?(operation.to_sym) == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def cancel_operation?(context:, resource:, operation:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, resource.model_class)
+        policy.respond_to?(:cancel_operation?) && policy.cancel_operation?(operation.to_sym) == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def named_scopes(context:, resource:)
+        klass = policy_class(resource)
+        return [] unless klass
+        policy = klass.new(context, resource.model_class)
+        policy.respond_to?(:permitted_named_scopes) ? policy.permitted_named_scopes : []
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def select_records?(context:, resource:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, resource.model_class)
+        policy.respond_to?(:select_records?) && policy.select_records? == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def export_records?(context:, resource:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, resource.model_class)
+        policy.respond_to?(:export_records?) && policy.export_records? == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def import_records?(context:, resource:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, resource.model_class)
+        policy.respond_to?(:import_records?) && policy.import_records? == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def view_audit_log?(context:, resource:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, resource.model_class)
+        policy.respond_to?(:view_audit_log?) && policy.view_audit_log? == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def view_history?(context:, resource:, record:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, record)
+        policy.respond_to?(:view_history?) && policy.view_history? == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      def assistant?(context:, resource:)
+        klass = policy_class(resource)
+        return false unless klass
+        policy = klass.new(context, resource.model_class)
+        policy.respond_to?(:assistant?) && policy.assistant? == true
+      rescue StandardError => error
+        policy_error!(resource, error)
+      end
+
+      private
+
+      def policy_class(resource)
+        name = resource.policy
+        return unless name
+        klass = name.safe_constantize
+        raise ConfigurationError, "Policy must resolve to a class" if klass && !klass.is_a?(Class)
+        klass
+      end
+
+      def scope_class(policy)
+        owner = policy.ancestors.take_while { |ancestor| ancestor != Object && ancestor != BasicObject }
+          .find { |ancestor| ancestor.is_a?(Class) && ancestor.const_defined?(:Scope, false) }
+        owner&.const_get(:Scope, false)
+      end
+
+      def policy_error!(resource, error)
+        raise ConfigurationError, "Pundit policy failed for #{resource.key} (#{error.class.name})", cause: nil
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/collections/claim.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  module Collections
+    # A server-created lease token. Public HTTP execution cannot supply one.
+    class Claim
+      attr_reader :item_ref, :parent_ref, :operation_run_id, :owner, :generation
+      def initialize(item)
+        @item_ref, @parent_ref, @operation_run_id = item.id, item.parent_run_id, item.operation_run_id
+        @owner, @generation = item.lease_owner, item.generation
+      end
+
+      def context
+        run = OperationRun.find(parent_ref)
+        @parent_snapshot = run
+        ActiveRecord::Base.while_preventing_writes do
+          adapter = RailsAiAdmin.configuration.context_adapter&.constantize&.new
+          raise AccessDenied, "APPROVAL_INVALIDATED" unless adapter&.respond_to?(:resolve_job)
+          current = adapter.resolve_job(actor_ref: run.actor_ref, tenant_ref: run.tenant_ref, security_version: run.security_version)
+          unless current.is_a?(Context) && current.actor_ref == run.actor_ref && current.tenant_ref == run.tenant_ref && current.security_version == run.security_version
+            raise AccessDenied, "APPROVAL_INVALIDATED"
+          end
+          current
+        end
+      rescue AccessDenied
+        raise AccessDenied, "APPROVAL_INVALIDATED", cause: nil
+      rescue ActiveRecord::ReadOnlyError
+        raise ConfigurationError, "Job context resolution must be read-only", cause: nil
+      end
+
+      def payload = @parent_snapshot.input_payload
+      def origin = @parent_snapshot.origin
+
+      def lock!(context)
+        @parent = Contract.owned(context, parent_ref, lock: true)
+        @item = BatchItem.lock.find_by(id: item_ref, parent_run_id: parent_ref, operation_run_id: operation_run_id)
+        verify_live!
+        @resource, @definition = Contract.definition(@parent)
+        Contract.verify_approved!(@parent, @definition, context)
+        begin
+          ActiveRecord::Base.while_preventing_writes do
+            access = Authorization::Access.new(context, @resource)
+            access.authorize!(@parent.operation)
+            current = InputSchema.new(@definition.fields(access, nil)).coerce(@parent.input_payload, time_zone: context.time_zone)
+            raise AccessDenied unless current.valid? && InputSchema.digest(current.values) == @parent.input_digest
+          end
+        rescue AccessDenied
+          raise AccessDenied, "AUTHORIZATION_REVOKED", cause: nil
+        end
+        unless @parent.manifest_payload[@item.position] == [ @item.target_id, @item.expected_version ]
+          raise AccessDenied, "APPROVAL_INVALIDATED"
+        end
+      end
+
+      def validate_child!(run, resource, definition)
+        unless resource.equal?(@resource) && definition.scope == :collection && run.parent_run_id == parent_ref &&
+            run.selection_id.nil? && run.target_id == @item.target_id && run.expected_version == @item.expected_version &&
+            run.actor_ref == @parent.actor_ref && run.tenant_ref == @parent.tenant_ref && run.security_version == @parent.security_version &&
+            run.resource_key == @parent.resource_key && run.operation == @parent.operation && run.operation_version == @parent.operation_version &&
+            run.input_digest == @parent.input_digest && run.origin == @parent.origin && run.expires_at == @parent.execution_deadline &&
+            run.approved_by_ref.nil? && run.confirmed_at.nil? && run.approved_digest.nil?
+          raise AccessDenied, "APPROVAL_INVALIDATED"
+        end
+      end
+
+      def complete!(run)
+        verify_live!
+        raise ConfigurationError, "Child receipt did not commit success" unless run.status == "succeeded"
+        @item.update!(status: "succeeded", last_code: "OK", completed_at: Time.current)
+        Contract.refresh!(@parent)
+        # Projection and all metadata writes must finish within the lease.
+        # Parent/item locks remain held through the encompassing business commit.
+        unless @item.lease_owner == owner && @item.generation == generation && @item.lease_expires_at > Time.current
+          raise AccessDenied, "FENCED"
+        end
+        raise AccessDenied, "EXECUTION_EXPIRED" unless @parent.execution_deadline > Time.current
+      end
+
+      private
+
+      def verify_live!
+        unless @item && @item.status == "running" && @item.lease_owner == owner && @item.generation == generation && @item.lease_expires_at && @item.lease_expires_at > Time.current
+          raise AccessDenied, "FENCED"
+        end
+        raise AccessDenied, "CANCELLED" if @parent.cancellation_requested_at
+        raise AccessDenied, "EXECUTION_EXPIRED" unless @parent.execution_deadline && @parent.execution_deadline > Time.current
+        raise AccessDenied, "FENCED" unless Contract::ACTIVE.include?(@parent.status)
+      end
+    end
+  end
+end