ace-assign 0.63.1 → 0.66.0

data/lib/ace/assign/organisms/delivery_coordinator.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+require "yaml"
+require "ace/git/organisms/pull_request_lifecycle"
+require_relative "../atoms/delivery_parameters"
+
+module Ace
+  module Assign
+    module Organisms
+      # Remote delivery is a projection of the existing attempt journal.
+      # Intents precede writes; an interrupted intent permits reconciliation
+      # reads only. Privileged merge is executed by qjx, never this worker.
+      class DeliveryCoordinator
+        def initialize(repo_root:, coordinator: nil, journal: nil, lifecycle_factory: nil, exclusion: nil, identity_resolver: nil)
+          @mutex = Mutex.new
+          @identity_resolver = identity_resolver || Molecules::ExecutionIdentityResolver.new
+          @repo_root = repo_root
+          @journal = journal || Molecules::EvidenceJournal.new(repo_root: repo_root)
+          @coordinator = coordinator || AttemptCoordinator.new(repo_root: repo_root, journal: @journal)
+          @factory = lifecycle_factory || ->(selection) { Ace::Git::Organisms::PullRequestLifecycle.new(**selection) }
+          @exclusion = exclusion || Molecules::LifecycleExclusion.new(repo_root: repo_root)
+        end
+
+        def perform(**arguments)
+          @mutex.synchronize { execute_request(**arguments) }
+        end
+
+        private
+
+        def execute_request(assignment_id:, attempt_id:, operation:, parameters: nil, title: nil, body: nil,
+          tests: nil, review: nil, service_request_id: nil)
+          @identity = @identity_resolver.resolve
+          unless @identity_resolver.trusted?(@identity)
+            raise AttemptErrors::UnauthorizedIdentity, "Only a trusted coordinator or service may accept delivery evidence"
+          end
+          raise ArgumentError, "Unsupported delivery operation" unless %w[create update ready review merge status].include?(operation)
+          if operation == "create" && (!title.is_a?(String) || title.strip.empty?)
+            raise ArgumentError, "Create requires a concrete PR title"
+          end
+          if operation == "update" && title.nil? && body.nil?
+            raise ArgumentError, "Update requires title or body"
+          end
+          raise ArgumentError, "PR body must be text" unless body.nil? || body.is_a?(String)
+          params = Atoms::DeliveryParameters.validate(parameters || assignment_parameters(assignment_id))
+          binding = {"assignment_id" => assignment_id, "attempt_id" => attempt_id}
+          attempt = @coordinator.authoritative_attempt(binding)
+          raise AttemptErrors::NotFound, "Delivery attempt not found" unless attempt
+          raise AttemptErrors::ReceiptRejected, "Delivery requires a managed attempt" unless attempt.managed?
+          @exclusion.with_shared(@exclusion.task_key(attempt.binding.task_id)) do
+            @exclusion.with_exclusive(@exclusion.assignment_key(assignment_id)) do
+              raise AttemptErrors::Conflict, "Assignment was pruned" if @exclusion.removed?(@exclusion.assignment_key(assignment_id))
+              execute(binding, operation, params, title: title, body: body, tests: tests, review: review,
+                service_request_id: service_request_id)
+            end
+          end
+        end
+
+        private
+
+        def assignment_parameters(assignment_id)
+          assignment = Molecules::AssignmentManager.new.load(assignment_id)
+          raise AttemptErrors::NotFound, "Assignment not found" unless assignment
+          document = YAML.safe_load_file(assignment.source_config, permitted_classes: [Time, Date])
+          document.fetch("delivery")
+        rescue KeyError, Errno::ENOENT, Psych::Exception
+          raise ArgumentError, "Assignment needs explicit delivery parameters"
+        end
+
+        def execute(binding, operation, params, **options)
+          @binding = binding
+          @intent_context = nil
+          @attempt = @coordinator.authoritative_attempt(binding)
+          unless @attempt&.active? && @attempt.managed?
+            raise AttemptErrors::ReceiptRejected, "Delivery attempt is no longer active"
+          end
+          @head = git!("rev-parse", "HEAD").strip
+          selection = {server_name: params["forge_server"], use_default: params["forge_default"], repo_root: @repo_root}
+          historical = events.find { |event| event.dig("payload", "stage") == "identity" }&.fetch("payload")
+          selection = {server_name: historical.dig("server", "name"), use_default: false, repo_root: @repo_root} if historical
+          @lifecycle = @factory.call(selection)
+          server = @lifecycle.resolved_identity
+          @server = server
+          Atoms::DeliveryParameters.validate_url!(server.fetch("url"))
+          provenance = params.fetch("pr_provenance")
+          unless Ace::Git::Atoms::ServerUrl.match?(server["url"], provenance["base_repository_url"])
+            raise Ace::Git::ProviderIdentityMismatchError, "Selected forge does not match delivery base"
+          end
+          if historical
+            unless historical["server"] == server && historical["provenance"] == provenance &&
+                historical["selection"] == params.slice("forge_server", "forge_default")
+              raise AttemptErrors::Conflict, "Delivery identity or selection changed during attempt"
+            end
+          elsif !%w[status review].include?(operation)
+            record("stage" => "identity", "server" => server, "provenance" => provenance,
+              "selection" => params.slice("forge_server", "forge_default"))
+          end
+          @provenance = provenance
+          pinned = Ace::Git::ResolvedServer.new(name: server.fetch("name"),
+            provider: server.fetch("provider").to_sym, url: server.fetch("url"))
+          @lifecycle = @factory.call(server_name: pinned.name, use_default: false,
+            repo_root: @repo_root, resolved_server: pinned)
+          verify_pushed_head!
+          return status if operation == "status"
+          return review_snapshot if operation == "review"
+          pending = unresolved_intent
+          if pending
+            result = reconcile(pending)
+            return result if same_effect?(pending, operation, options)
+            raise AttemptErrors::CurrentEffectRequired.new(operation: operation, recovered_operation: pending["operation"])
+          end
+          require_evidence!(options[:tests], options[:review]) if %w[ready merge].include?(operation)
+          return consume_merge(options[:service_request_id]) if operation == "merge"
+          pr = current_pr
+          if operation == "create" && pr
+            requested = content_input(options)
+            metadata = @lifecycle.review_metadata_snapshot(pr.number).pull_request
+            verify_pr!(metadata)
+            unless content_matches?(requested.keys.map(&:to_s), Atoms::EvidenceDigest.digest(requested), metadata)
+              raise AttemptErrors::CurrentEffectRequired.new(operation: operation, recovered_operation: "create")
+            end
+            return reconcile({"operation" => "create", "head" => @head,
+              "fields" => requested.keys.map(&:to_s), "input_digest" => Atoms::EvidenceDigest.digest(requested)})
+          end
+          raise AttemptErrors::ReceiptRejected, "Create a draft before #{operation}" if operation != "create" && !pr
+          verify_pr!(pr) if pr
+          intent = {"stage" => "intent", "operation" => operation, "head" => @head,
+                    "input_digest" => Atoms::EvidenceDigest.digest(content_input(options)),
+                    "fields" => content_input(options).keys.map(&:to_s),
+                    "pr_number" => pr&.number, "tests" => options[:tests], "review" => options[:review]}
+          record(intent)
+          @intent_context = unresolved_intent
+          receipt = case operation
+          when "create"
+            @lifecycle.create(head_ref: provenance["head_ref"], base_ref: provenance["base_ref"],
+              head_repository_url: provenance["head_repository_url"], expected_head: @head,
+              title: options[:title], body: options[:body], draft: true)
+          when "update"
+            @lifecycle.update(pr.number, expected_head: @head, title: options[:title], body: options[:body])
+          when "ready" then @lifecycle.ready(pr.number, expected_head: @head)
+          end
+          verify_pr!(receipt.pull_request)
+          unless receipt.operation.to_s == operation && receipt.server_name == server["name"] &&
+              (operation != "create" || receipt.pull_request.draft == true) &&
+              (operation != "ready" || receipt.pull_request.draft == false)
+            raise Ace::Git::ProviderUnknownOutcomeError, "Delivery mutation lacks expected outcome"
+          end
+          record_result(operation, receipt.pull_request, "succeeded")
+          status
+        rescue Ace::Git::ProviderUnknownOutcomeError
+          # The durable intent remains unresolved; no exception text or
+          # provider payload is stored (both may contain sensitive data).
+          raise
+        end
+
+        def events
+          @journal.read_events(@binding.fetch("assignment_id")).select do |event|
+            event["type"] == "delivery"
+          end
+        end
+
+        def record(payload)
+          producer = {"actor" => @identity.actor, "role" => @identity.role, "runtime" => @identity.runtime}
+          @journal.record(**@binding.transform_keys(&:to_sym), type: "delivery", payload: payload.merge("producer" => producer),
+            guard: -> {
+              live = @coordinator.authoritative_attempt(@binding)
+              raise AttemptErrors::ReceiptRejected, "Delivery attempt is no longer active" unless live&.active?
+              raise AttemptErrors::ReceiptRejected, "Candidate changed during delivery" unless git!("rev-parse", "HEAD").strip == @head
+            })
+        end
+
+        def unresolved_intent
+          history = events
+          settled = history.filter_map do |event|
+            payload = event.fetch("payload")
+            payload["intent_digest"] if payload["stage"] == "result" && payload["outcome"] == "succeeded"
+          end
+          pending = history.select do |event|
+            event.dig("payload", "stage") == "intent" && !settled.include?(event["digest"])
+          end
+          raise AttemptErrors::Conflict, "Multiple unresolved delivery intents require reconciliation" if pending.length > 1
+          event = pending.first
+          event && event.fetch("payload").merge("intent_digest" => event.fetch("digest"),
+            "intent_attempt_id" => event.fetch("attempt_id"))
+        end
+
+        def current_pr
+          result = events.reverse.find { |event| event.dig("payload", "stage") == "result" && event.dig("payload", "pr") }
+          result && @lifecycle.show(result.dig("payload", "pr", "number"))
+        end
+
+        def reconcile(intent)
+          @intent_context = intent
+          raise AttemptErrors::ReceiptRejected, "Unresolved delivery belongs to an older candidate" unless intent["head"] == @head
+          operation = intent.fetch("operation")
+          if operation == "create"
+            matches = @lifecycle.reconcile_create(**@provenance.reject { |key, _| key == "mode" }.transform_keys(&:to_sym))
+            raise Ace::Git::ProviderUnknownOutcomeError, "No exact draft found; create remains unresolved" if matches.empty?
+            raise Ace::Git::ProviderConflictingMatchesError, "Multiple exact drafts found" unless matches.length == 1
+            pr = matches.first
+            verify_pr!(pr)
+            raise Ace::Git::ProviderUnknownOutcomeError, "Created PR draft state is unproven" unless pr.draft == true
+            pr = @lifecycle.review_metadata_snapshot(pr.number).pull_request
+            verify_pr!(pr)
+            unless content_matches?(intent.fetch("fields"), intent.fetch("input_digest"), pr)
+              raise Ace::Git::ProviderUnknownOutcomeError, "Created PR content remains unproven"
+            end
+          elsif operation == "ready"
+            require_evidence!(intent["tests"], intent["review"])
+            pr = @lifecycle.show(intent.fetch("pr_number"))
+            verify_pr!(pr)
+            raise Ace::Git::ProviderUnknownOutcomeError, "Readiness remains unresolved" unless pr.draft == false
+          elsif operation == "update"
+            pr = @lifecycle.review_metadata_snapshot(intent.fetch("pr_number")).pull_request
+            verify_pr!(pr)
+            unless content_matches?(intent.fetch("fields"), intent.fetch("input_digest"), pr)
+              raise Ace::Git::ProviderUnknownOutcomeError, "PR update remains unresolved"
+            end
+          else
+            raise Ace::Git::ProviderUnknownOutcomeError, "#{operation} requires authoritative receipt reconciliation"
+          end
+          record_result(operation, pr, "succeeded")
+          status
+        end
+
+        def content_input(options)
+          options.slice(:title, :body).compact
+        end
+
+        def content_matches?(fields, digest, pr)
+          observed = fields.to_h { |field| [field, pr.public_send(field)] }
+          Atoms::EvidenceDigest.digest(observed) == digest
+        end
+
+        def same_effect?(intent, operation, options)
+          return false unless intent["operation"] == operation
+          case operation
+          when "create", "update"
+            intent["input_digest"] == Atoms::EvidenceDigest.digest(content_input(options))
+          when "ready"
+            %i[tests review].all? { |key| options[key].nil? || options[key] == intent[key.to_s] }
+          when "merge"
+            options[:service_request_id].is_a?(String) &&
+              options[:service_request_id] == intent["service_request_id"] &&
+              %i[tests review].all? { |key| options[key].nil? || options[key] == intent[key.to_s] }
+          else false
+          end
+        end
+
+        def require_evidence!(tests, review)
+          [[tests, "check"], [review, "review-approval"]].each do |ref, kind|
+            unless ref.is_a?(Hash) && ref.keys.sort == %w[attempt_id receipt_digest]
+              raise AttemptErrors::ReceiptRejected, "Current accepted #{kind} evidence is required"
+            end
+            evidence = @coordinator.evidence(attempt_id: ref["attempt_id"], receipt_digest: ref["receipt_digest"], kind: kind)
+            unless evidence["head"] == @head && evidence["assignment_id"] == @binding["assignment_id"] &&
+                evidence["project_id"] == @attempt.binding.project_id
+              raise AttemptErrors::ReceiptRejected, "Delivery evidence does not match assignment, project and candidate"
+            end
+          end
+        end
+
+        def consume_merge(request_id)
+          unless request_id.is_a?(String) && request_id.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/)
+            raise AttemptErrors::ReceiptRejected, "Exact authorized merge service receipt is required"
+          end
+          request = @coordinator.service_request_status(request_id)
+          unless request && request["state"] == "succeeded" && request["operation"] == "merge" &&
+              request["assignment_id"] == @binding["assignment_id"] && request["attempt_id"] == @binding["attempt_id"] &&
+              request["project_id"] == @attempt.binding.project_id && request["candidate_head"] == @head &&
+              request["authorization"].is_a?(String) && !request["authorization"].empty?
+            raise AttemptErrors::ReceiptRejected, "Exact authorized merge service receipt is required"
+          end
+          @coordinator.validate_service_receipt!(request, "succeeded", request["receipt"])
+          pr = current_pr
+          verify_pr!(pr)
+          unless request.dig("target", "resource") == pr.url && pr.state.to_s == "merged" &&
+              pr.merge_commit_sha.to_s.match?(/\A[0-9a-f]{40}\z/)
+            raise AttemptErrors::ReceiptRejected, "Service receipt and merged PR identity do not agree"
+          end
+          record_result("merge", pr, "succeeded", "service_request_id" => request_id)
+          status
+        end
+
+        def review_snapshot
+          pr = current_pr
+          raise AttemptErrors::ReceiptRejected, "Create a draft before remote review" unless pr
+          verify_pr!(pr)
+          snapshot = @lifecycle.review_snapshot(pr.number)
+          verify_pr!(snapshot.pull_request)
+          snapshot
+        end
+
+        def verify_pr!(pr)
+          reference = pr && Ace::Git::Atoms::PrReference.parse(pr.url)
+          unless reference && reference.number == pr.number && reference.repository_url &&
+              Ace::Git::Atoms::ServerUrl.match?(reference.repository_url, @provenance["base_repository_url"])
+            raise Ace::Git::ProviderIdentityMismatchError, "PR URL does not match delivery repository and number"
+          end
+          Atoms::DeliveryParameters.validate_url!(pr.url)
+          unless pr && pr.server_name == @server["name"] && pr.number.is_a?(Integer) && pr.number.positive? &&
+              pr.head_sha == @head && pr.head_ref == @provenance["head_ref"] &&
+              pr.base_ref == @provenance["base_ref"] &&
+              Ace::Git::Atoms::ServerUrl.match?(pr.head_repository_url, @provenance["head_repository_url"]) &&
+              Ace::Git::Atoms::ServerUrl.match?(pr.base_repository_url, @provenance["base_repository_url"])
+            raise Ace::Git::ProviderExpectedHeadConflictError, "PR candidate or provenance does not match delivery"
+          end
+        end
+
+        def verify_pushed_head!
+          output = git!("ls-remote", "--heads", @provenance["head_repository_url"], "refs/heads/#{@provenance['head_ref']}")
+          expected = "#{@head}\trefs/heads/#{@provenance['head_ref']}"
+          raise AttemptErrors::ReceiptRejected, "Pushed source does not match candidate" unless output.strip == expected
+        end
+
+        def record_result(operation, pr, outcome, extra = {})
+          record({"stage" => "result", "operation" => operation, "head" => @head, "outcome" => outcome,
+            "intent_digest" => @intent_context&.fetch("intent_digest", nil),
+            "intent_attempt_id" => @intent_context&.fetch("intent_attempt_id", nil),
+            "pr" => {"number" => pr.number, "url" => pr.url, "head_sha" => pr.head_sha,
+                     "draft" => pr.draft, "state" => pr.state.to_s, "merge_commit_sha" => pr.merge_commit_sha}}.merge(extra))
+        end
+
+        def status
+          attempt = @coordinator.authoritative_attempt(@binding)
+          {"attempt_id" => attempt.attempt_id, "assignment_id" => @binding["assignment_id"],
+           "task_id" => attempt.binding.task_id, "project_id" => attempt.binding.project_id,
+           "actor" => attempt.binding.actor, "role" => attempt.binding.role, "runtime" => attempt.binding.runtime,
+           "base_head" => attempt.binding.base_head, "candidate_head" => attempt.candidate_head,
+           "evidence_git_ref" => @attempt.binding.evidence_git_ref, "journal_commit" => @journal.ref_value,
+           "delivery" => events.map do |event|
+             event.fetch("payload").merge("attempt_id" => event.fetch("attempt_id"), "event_digest" => event.fetch("digest"))
+           end}
+        end
+
+        def git!(*argv)
+          result = Ace::Git::Atoms::CommandExecutor.execute("git", "-C", @repo_root, *argv)
+          raise AttemptErrors::EvidenceUnavailable, "Git delivery proof unavailable" unless result[:success]
+          result[:output]
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/organisms/prepared_work_builder.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "ace/bundle"
+require_relative "task_assignment_creator"
+require_relative "../authority/prepared_work"
+
+module Ace
+  module Assign
+    module Organisms
+      # Captures managed preparation once. This owner neither registers nor
+      # launches work; callers retain its exact output across uncertain replies.
+      class PreparedWorkBuilder
+        def initialize(export_root:, task_manager: nil, executor: nil, bundle_loader: nil)
+          @tasks = task_manager || Ace::Task::Organisms::TaskManager.new
+          @executor = executor || AssignmentExecutor.new
+          @bundles = bundle_loader || Ace::Bundle::Organisms::BundleLoader.new
+          @transfer = Authority::CandidateTransfer.new(root: export_root)
+        end
+
+        def call(task_ref:, project_id:, dependency_reports:)
+          token!(project_id)
+          @reads = {}
+          @inventories = {}
+          tasks = closure(task_ref)
+          selected = tasks.fetch(task_ref)
+          refuse!("selected task is not a reviewed leaf") unless
+            %w[pending in-progress].include?(selected.status.to_s) && Array(selected.subtasks).empty?
+          contexts = tasks.sort.to_h do |id, task|
+            refuse!("task still needs review") unless task.metadata.fetch("needs_review", false) == false
+            [id, capture_context(task)]
+          end
+          reports = capture_reports(dependency_reports, tasks, task_ref, project_id)
+          result = TaskAssignmentCreator.new(task_manager: @tasks, executor: @executor)
+            .call(task_refs: [task_ref], primary_task_ref: task_ref, project_id: project_id)
+          assignment = result.fetch(:assignment)
+          refuse!("managed association changed") unless assignment.task_id == task_ref && assignment.project_id == project_id
+          job = read(assignment.source_config)
+          read(assignment.assignment_file)
+          inventory = inventory(assignment.steps_dir)
+          step_files = inventory.to_h { |name| [name, read(File.join(assignment.steps_dir, name))] }
+          roots = step_files.filter_map do |name, bytes|
+            fm = Atoms::StepFileParser.parse(bytes).fetch(:frontmatter)
+            Atoms::StepFileParser.parse_filename(name).fetch(:number) if fm["context"] == "fork" && fm["taskref"] == task_ref
+          end
+          refuse!("selected fork root is not unique") unless roots.one? && roots.first
+          scope = roots.first
+          files = {"definition.json" => JSON.generate(assignment.to_h), "job.yaml" => job}
+          selected_steps = step_files.filter_map do |name, bytes|
+            number = Atoms::StepFileParser.parse_filename(name).fetch(:number)
+            refuse!("unexpected queue entry") unless number && name.end_with?(".st.md")
+            next unless number == scope || number.start_with?(scope + ".")
+            files["steps/#{name}"] = bytes
+            record(name, bytes).merge("number" => number)
+          end.sort_by { |entry| number_key(entry.fetch("number")) }
+          context = contexts.map do |id, captured|
+            spec_path = "context/#{id}/spec.md"
+            text_path = "context/#{id}/bundle.txt"
+            files[spec_path], files[text_path] = captured.values_at(:spec, :text)
+            selected_reports = reports.fetch(id, []).map do |report|
+              path = "context/#{id}/reports/#{report.fetch(:assignment_id)}/#{report.fetch(:number)}.r.md"
+              files[path] = report.fetch(:bytes)
+              {"assignment_id" => report.fetch(:assignment_id), "number" => report.fetch(:number),
+                "file" => record(path, report.fetch(:bytes))}
+            end
+            {"uri" => "task://#{id}", "task_id" => id, "spec" => record(spec_path, files.fetch(spec_path)),
+              "text" => record(text_path, files.fetch(text_path)), "reports" => selected_reports}
+          end
+          manifest = {"version" => 1, "assignment_id" => assignment.id, "project_id" => project_id,
+            "task_id" => task_ref, "scope" => scope, "job" => record("job.yaml", job),
+            "steps" => selected_steps, "context" => context}
+          files["manifest.json"] = Authority::PreparedWork.canonical_manifest(manifest) + "\n"
+          work = Authority::PreparedWork.new(files: files)
+          current = closure(task_ref)
+          refuse!("task dependency inventory changed") unless current.keys.sort == tasks.keys.sort
+          refuse!("selected task expanded during capture") unless Array(current.fetch(task_ref).subtasks).empty?
+          current.each { |id, task| refuse!("task context changed") unless capture_context(task) == contexts.fetch(id) }
+          @inventories.each { |path, names| refuse!("input inventory changed") unless Dir.children(path).sort == names }
+          @reads.each { |path, bytes| refuse!("captured input changed") unless read_bytes(path) == bytes }
+          @transfer.export_prepared(work: work).merge("assignment_id" => assignment.id,
+            "scope" => scope.freeze, "selection_sha256" => work.selection_sha256).freeze
+        ensure
+          @reads = nil
+          @inventories = nil
+        end
+
+        private
+
+        def closure(ref)
+          found = {}; visiting = []
+          walk = lambda do |id|
+            token!(id)
+            refuse!("dependency cycle: #{(visiting + [id]).join(' -> ')}") if visiting.include?(id)
+            return if found.key?(id)
+            refuse!("too many task contexts") if found.size >= 256
+            task = @tasks.show(id)
+            refuse!("missing or noncanonical task") unless task && task.id == id
+            found[id] = task
+            visiting << id
+            Array(task.dependencies).each { |dependency| walk.call(dependency) }
+            visiting.pop
+          end
+          walk.call(ref)
+          found
+        end
+
+        def capture_context(task)
+          spec = read(task.file_path)
+          bundle = @bundles.load_file(task.file_path)
+          errors = bundle.metadata.values_at(:error, :errors, "error", "errors").flatten.compact
+          refuse!("unresolvable task context") unless errors.empty?
+          text = bounded_text(bundle.content)
+          # Deep-copy owner inventories; a loader may reuse mutable objects.
+          {spec: spec, text: text, path: task.file_path,
+            inventory: Marshal.dump([bundle.files, bundle.source_files])}
+        end
+
+        def capture_reports(selections, tasks, selected, project)
+          refuse!("report selections must be explicit") unless selections.is_a?(Array) && selections.size <= 4096
+          seen = {}; grouped = Hash.new { |hash, key| hash[key] = [] }
+          selections.each do |selection|
+            refuse!("report selector") unless selection.is_a?(Hash) && selection.keys.sort == %w[assignment_id number task_id]
+            id, assignment_id, number = selection.values_at("task_id", "assignment_id", "number")
+            token!(id); token!(assignment_id)
+            refuse!("report scope") unless number.is_a?(String) && number.match?(Authority::PreparedWork::SCOPE)
+            refuse!("report is not a dependency") unless id != selected && tasks.key?(id)
+            identity = [id, assignment_id, number]
+            refuse!("duplicate report") if seen[identity]
+            seen[identity] = true
+            assignment = @executor.assignment_manager.load(assignment_id)
+            refuse!("report assignment association") unless assignment && assignment.task_id == id && assignment.project_id == project
+            metadata = read(assignment.assignment_file)
+            parsed_metadata = YAML.safe_load(metadata, permitted_classes: [Time, Date])
+            refuse!("report assignment changed") unless parsed_metadata["session_id"] == assignment_id &&
+              parsed_metadata["task_id"] == id && parsed_metadata["project_id"] == project
+            inventory(assignment.reports_dir)
+            matches = inventory(assignment.steps_dir).select do |name|
+              name.end_with?(".st.md") && Atoms::StepFileParser.parse_filename(name)[:number] == number
+            end
+            refuse!("report step association") unless matches.one?
+            step = matches.first
+            read(File.join(assignment.steps_dir, step))
+            parsed = Atoms::StepFileParser.parse_filename(step)
+            filename = Atoms::StepFileParser.generate_report_filename(number, parsed.fetch(:name))
+            grouped[id] << {assignment_id: assignment_id, number: number,
+              bytes: read(File.join(assignment.reports_dir, filename))}
+          end
+          grouped.each_value { |entries| entries.sort_by! { |entry| [entry.fetch(:assignment_id), number_key(entry.fetch(:number))] } }
+          grouped
+        end
+
+        def record(path, bytes)
+          {"filename" => path, "bytes" => bytes.bytesize, "sha256" => Digest::SHA256.hexdigest(bytes)}
+        end
+
+        def read(path)
+          bytes = read_bytes(path)
+          refuse!("captured input changed") if @reads.key?(path) && @reads.fetch(path) != bytes
+          @reads[path] = bytes
+          refuse!("capture inventory bound") if @reads.size > 4096 || @reads.values.sum(&:bytesize) > Authority::PreparedWork::MAX_TOTAL
+          bytes
+        end
+
+        def inventory(path)
+          names = Dir.children(path).sort.freeze
+          refuse!("capture inventory bound") if names.size > 4096
+          refuse!("input inventory changed") if @inventories.key?(path) && @inventories.fetch(path) != names
+          @inventories[path] = names
+        end
+
+        def read_bytes(path)
+          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+            refuse!("input is not a bounded regular file") unless file.stat.file? && file.stat.size <= Authority::PreparedWork::MAX_TEXT
+            bounded_text(file.read(Authority::PreparedWork::MAX_TEXT + 1))
+          end
+        rescue SystemCallError
+          refuse!("input unavailable")
+        end
+
+        def bounded_text(bytes)
+          refuse!("input text bound") unless bytes.is_a?(String) && bytes.bytesize.between?(1, Authority::PreparedWork::MAX_TEXT)
+          text = bytes.dup.force_encoding(Encoding::UTF_8)
+          refuse!("input encoding") unless text.valid_encoding? && !text.include?("\0")
+          text.freeze
+        end
+
+        def number_key(number) = number.split(".").map(&:to_i)
+        def token!(value)
+          refuse!("invalid identity") unless value.is_a?(String) && value.match?(Authority::PreparedWork::TOKEN)
+        end
+        def refuse!(message) = raise(AttemptErrors::ReceiptRejected, "prepared_input_invalid: #{message}")
+      end
+    end
+  end
+end

data/lib/ace/assign/organisms/protected_delivery_coordinator.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+require_relative "../authority/service_delivery_evidence"
+require "ace/git/atoms/service_pr_evidence"
+
+module Ace
+  module Assign
+    module Organisms
+      # Worker consumes only the original authority's canonical completion.
+      # No local journal, provider mutation, recovery write or merge retry.
+      class ProtectedDeliveryCoordinator
+        BASE_FIELDS = %w[request_id assignment_id attempt_id project_id operation service_id target candidate_head
+          candidate_generation state dispatch_ticket_id claim_binding claim_generation dispatch_phase policy_digest generation journal_commit].freeze
+        COMPLETE_FIELDS = %w[input_digest authorization executor_uid completion_digest receipt delivery_event].freeze
+
+        def initialize(client:, project_id:)
+          @client, @project_id = client, project_id
+        end
+
+        def perform(assignment_id:, attempt_id:, operation:, service_request_id:, candidate_head:, candidate_generation:,
+          input_digest:, target:, parameters: nil, title: nil, body: nil, tests: nil, review: nil)
+          unless %w[create update ready merge status].include?(operation) && [title, body, tests, review].all?(&:nil?) &&
+              [assignment_id, attempt_id, service_request_id].all? { |value| value.is_a?(String) && value.match?(Molecules::JournalMutation::ID) } &&
+              candidate_head.is_a?(String) && candidate_head.match?(/\A[0-9a-f]{40}\z/) &&
+              candidate_generation.is_a?(Integer) && candidate_generation.positive? &&
+              input_digest.is_a?(String) && input_digest.match?(/\A[0-9a-f]{64}\z/) &&
+              target.is_a?(Hash) && target.keys.sort == %w[artifact_digest resource] && target["resource"].is_a?(String) &&
+              (target["artifact_digest"].nil? || target["artifact_digest"].is_a?(String) && target["artifact_digest"].match?(/\A[0-9a-f]{64}\z/))
+            raise ArgumentError, "protected delivery requires exact canonical merge selectors; local delivery flags are unavailable"
+          end
+          binding = {"assignment_id" => assignment_id, "attempt_id" => attempt_id,
+            "candidate_generation" => candidate_generation, "head" => candidate_head, "request_id" => service_request_id}
+          data = @client.call("service_status", binding).data
+          unless data.is_a?(Hash) && (data.keys - BASE_FIELDS - COMPLETE_FIELDS).empty? &&
+              Atoms::EvidenceDigest.digest(data.slice("assignment_id", "attempt_id", "request_id", "candidate_generation")) == Atoms::EvidenceDigest.digest(binding.except("head")) &&
+              data["project_id"] == @project_id && data["candidate_head"] == candidate_head && Atoms::EvidenceDigest.digest(data["target"]) == Atoms::EvidenceDigest.digest(target) &&
+              %w[create update ready merge].include?(data["operation"]) && (operation == "status" || data["operation"] == operation) && data["generation"].is_a?(Integer) && data["generation"].positive? &&
+              data["input_digest"] == input_digest &&
+              data["journal_commit"].is_a?(String) && data["journal_commit"].match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/)
+            raise AttemptErrors::ReceiptRejected, "original canonical merge status differs"
+          end
+          if data["state"] != "succeeded"
+            return data if operation == "status"
+            raise AttemptErrors::EvidenceUnavailable, "original merge is not canonically succeeded; inspect its status without retry"
+          end
+          unless data.keys.sort == (BASE_FIELDS + COMPLETE_FIELDS).sort && data["input_digest"] == input_digest &&
+              data["executor_uid"].is_a?(Integer) && data["executor_uid"].positive? &&
+              data["completion_digest"].is_a?(String) && data["completion_digest"].match?(/\A[0-9a-f]{64}\z/)
+            raise AttemptErrors::ReceiptRejected, "original canonical completion selectors differ"
+          end
+          receipt = data.fetch("receipt")
+          unless receipt.is_a?(Hash) && receipt.keys.sort == Molecules::EvidenceJournal::TERMINAL_RECEIPT_FIELDS.sort &&
+              receipt["outcome"] == "succeeded" && receipt["operation"] == data["operation"] && receipt["transport"] == "unix" &&
+              receipt.slice("request_id", "assignment_id", "attempt_id", "project_id", "input_digest", "target", "candidate_head", "executor_uid") ==
+                data.slice("request_id", "assignment_id", "attempt_id", "project_id", "input_digest", "target", "candidate_head", "executor_uid") &&
+              receipt["evidence"].is_a?(Array) && receipt["evidence"].one?
+            raise AttemptErrors::ReceiptRejected, "original canonical merge receipt differs"
+          end
+          reference = receipt.fetch("evidence").first
+          unless reference.is_a?(Hash) && reference.keys.sort == %w[ref sha256] &&
+              reference["ref"].is_a?(String) && reference["ref"].match?(%r{\Aevidence/imports/[a-z0-9-]+\z}) &&
+              reference["sha256"].is_a?(String) && reference["sha256"].match?(/\A[0-9a-f]{64}\z/)
+            raise AttemptErrors::ReceiptRejected, "original canonical artifact reference differs"
+          end
+          fetched = @client.call("evidence_fetch", {"assignment_id" => assignment_id, "attempt_id" => attempt_id,
+            "kind" => "service", "purpose_id" => service_request_id,
+            "artifact_id" => reference.fetch("ref").delete_prefix("evidence/imports/")}, download: true, purpose: :artifacts)
+          descriptor = fetched.data.fetch("descriptor")
+          original_binding = Authority::ServiceEvidence::FIELDS.to_h { |key| [key, receipt.key?(key) ? receipt.fetch(key) : data.fetch(key)] }
+          unless Molecules::CanonicalEvidence.valid_descriptor?(descriptor) &&
+              descriptor["binding_digest"] == Atoms::EvidenceDigest.digest(original_binding) &&
+              descriptor["sha256"] == reference.fetch("sha256") && descriptor["peer_uid"] == data.fetch("executor_uid") &&
+              fetched.parts.is_a?(Array) && fetched.parts.one? && fetched.parts.first.is_a?(String) &&
+              Digest::SHA256.hexdigest(fetched.parts.first) == reference.fetch("sha256")
+            raise AttemptErrors::ReceiptRejected, "original canonical artifact descriptor differs"
+          end
+          proof_options = {request_id: service_request_id, input_digest: input_digest, target: target, head: candidate_head}
+          proof = if data.fetch("operation") == "merge"
+            Ace::Git::Atoms::ServiceMergeEvidence.validate(fetched.parts.first, **proof_options)
+          else
+            Ace::Git::Atoms::ServicePrEvidence.validate(fetched.parts.first, operation: data.fetch("operation"), **proof_options)
+          end
+          unless Atoms::EvidenceDigest.digest(proof.fetch(:input)) == input_digest &&
+              (!parameters || Atoms::EvidenceDigest.digest(Atoms::DeliveryParameters.validate(parameters)) == Atoms::EvidenceDigest.digest(proof.fetch(:input).fetch("delivery")))
+            raise AttemptErrors::ReceiptRejected, "canonical merge artifact accepted input differs"
+          end
+          event = data.fetch("delivery_event")
+          expected = Authority::ServiceDeliveryEvidence.payload(data, receipt, data.fetch("completion_digest"), proof)
+          unless event.is_a?(Hash) && event.keys.sort == %w[attempt_id digest payload previous_digest recorded_at type] &&
+              event["type"] == "delivery" && event["attempt_id"] == attempt_id && Models::EvidenceEvent.valid?(event) &&
+              Atoms::EvidenceDigest.digest(event.fetch("payload")) == Atoms::EvidenceDigest.digest(expected)
+            raise AttemptErrors::ReceiptRejected, "canonical delivery result/completion/import join differs"
+          end
+          data
+        rescue KeyError, TypeError, ArgumentError
+          raise AttemptErrors::ReceiptRejected, "protected merge evidence is malformed or unavailable"
+        end
+      end
+    end
+  end
+end