ace-assign 0.71.0 → 0.73.0

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

@@ -1,342 +0,0 @@
-# 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/ordinary_driver.rb

@@ -1,310 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-require "tmpdir"
-require "fileutils"
-require_relative "../authority/retained_input"
-require_relative "../authority/prepared_work"
-require_relative "../authority/transfer_codec"
-require_relative "../molecules/journal_mutation"
-require_relative "../models/execution_receipt"
-require_relative "../models/assignment"
-require_relative "../molecules/queue_scanner"
-
-module Ace
-  module Assign
-    module Organisms
-      # Operator protocol over the installed owner supplied by the composition.
-      # Files retain requests only; every observation comes from that owner.
-      class OrdinaryDriver
-        Files = Authority::RetainedInput
-        CONTEXT_KEYS = %w[version project_id assignment_id attempt_id scope pane supervisor_pane cwd head provider].freeze
-        attr_reader :context, :path
-
-        def initialize(path:, project:, transport:)
-          @path = File.expand_path(path)
-          @context = Files.json(@path)
-          unless @context.is_a?(Hash) && @context.keys.sort == CONTEXT_KEYS.sort && @context["version"] == 1 &&
-              @context["project_id"] == project && %w[project_id assignment_id attempt_id].all? { |key|
-                @context[key].is_a?(String) && Molecules::JournalMutation::ID.match?(@context[key]) } &&
-              @context["scope"].is_a?(String) && Authority::PreparedWork::SCOPE.match?(@context["scope"]) &&
-              %w[pane supervisor_pane].all? { |key| @context[key].is_a?(String) && @context[key].match?(/\A[\w.:-]{1,128}\z/) } &&
-              @context["cwd"].is_a?(String) && @context["cwd"].start_with?("/") &&
-              File.expand_path(@context["cwd"]) == @context["cwd"] && @context["head"].is_a?(String) &&
-              @context["head"].match?(/\A[0-9a-f]{40}\z/) && @context["provider"].is_a?(String) &&
-              @context["provider"].bytesize.between?(1, 512)
-            raise ArgumentError, "ordinary driver selection differs; retain the original context"
-          end
-          @root = Authority::PrivateDirectory.verify!(File.dirname(@path))
-          @transport = transport
-        end
-
-        def status
-          reply = read("result_status", selection)
-          data = reply.fetch("data")
-          unless data.values_at("project_id", "assignment_id", "attempt_id") == context.values_at("project_id", "assignment_id", "attempt_id")
-            raise AttemptErrors::EvidenceUnavailable, "canonical status belongs to another execution"
-          end
-          data
-        end
-
-        def start(pane:)
-          worker!(pane)
-          mutate("start", "start_attempt", selection.merge("expected_generation" => 0,
-            "pane" => pane, "scope" => context.fetch("scope"), "head" => context.fetch("head")))
-        end
-
-        def supervisor
-          data = read("supervisor_status", context.slice("assignment_id")).fetch("data")
-          unless data.values_at("project_id", "assignment_id") == context.values_at("project_id", "assignment_id")
-            raise AttemptErrors::EvidenceUnavailable, "canonical supervisor belongs to another assignment"
-          end
-          data
-        end
-
-        def adopt_supervisor(pane:, generation:, previous_binding_sha256:)
-          mutate("supervisor-#{generation}", "adopt_supervisor", context.slice("assignment_id").merge(
-            "pane" => pane, "expected_generation" => generation, "previous_binding_sha256" => previous_binding_sha256))
-        end
-
-        def queue
-          reply, bytes = snapshot("assignment_snapshot", selection.merge("kind" => "queue"))
-          data = reply.fetch("data")
-          unless data.values_at("project_id", "assignment_id", "attempt_id", "scope") ==
-              context.values_at("project_id", "assignment_id", "attempt_id", "scope") &&
-              Digest::SHA256.hexdigest(bytes) == data.fetch("sha256")
-            raise AttemptErrors::EvidenceUnavailable, "canonical queue belongs to another execution"
-          end
-          value = JSON.parse(bytes)
-          assignment = Models::Assignment.new(id: context.fetch("assignment_id"), name: "ordinary",
-            created_at: Time.now.utc, source_config: "canonical", cache_dir: @root)
-          state = Molecules::QueueScanner.new.scan_captured(steps: value.fetch("steps"),
-            reports: value.fetch("reports"), assignment: assignment)
-          scope = context.fetch("scope")
-          current = state.current_in_subtree(scope)
-          next_step = state.next_workable_in_subtree(scope)
-          data.merge("complete" => state.subtree_complete?(scope), "failed" => state.subtree_failed?(scope),
-            "current" => step(current), "next" => step(next_step), "reports" => value.fetch("reports"))
-        end
-
-        def bootstrap(output:)
-          # Accepted task/context bytes are recovered from the canonical owner,
-          # not the worker checkout's possibly older mutable task files.
-          reply, bytes = snapshot("assignment_snapshot", selection.merge("attempt_id" => nil, "kind" => "prepared_work"))
-          data = reply.fetch("data")
-          unless data.values_at("project_id", "assignment_id") == context.values_at("project_id", "assignment_id")
-            raise AttemptErrors::EvidenceUnavailable, "canonical preparation belongs to another assignment"
-          end
-          reference = data.fetch("prepared_work")
-          work = Authority::PreparedWork.admit(bytes: bytes, sha256: data.fetch("sha256"), size: data.fetch("bytes"),
-            head: reference.fetch("prepared_head"), tree: reference.fetch("prepared_tree"), root: @root,
-            deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30)
-          unless work.reference(head: reference.fetch("prepared_head"), tree: reference.fetch("prepared_tree")) == reference &&
-              work.manifest.values_at("project_id", "assignment_id", "scope") == context.values_at("project_id", "assignment_id", "scope")
-            raise AttemptErrors::EvidenceUnavailable, "canonical prepared scope differs"
-          end
-          directory = Files.create_output(output)
-          inventory = work.manifest.fetch("context").each_with_index.flat_map do |entry, index|
-            selected = %w[spec text].map { |kind| [kind, entry.fetch(kind)] } +
-              entry.fetch("reports").each_with_index.map { |report, number| ["report-#{number}", report.fetch("file")] }
-            selected.map do |kind, source|
-              content = work.files.fetch(source.fetch("filename"))
-              filename = "context-#{index}-#{kind}.md"
-              Files.write_file(directory, filename, content)
-              {"task_id" => entry.fetch("task_id"), "kind" => kind, "path" => File.join(directory, filename),
-                "sha256" => Digest::SHA256.hexdigest(content), "bytes" => content.bytesize}
-            end
-          end
-          {"project_id" => context.fetch("project_id"), **selection, "scope" => context.fetch("scope"),
-            "manifest_sha256" => work.manifest_sha256, "files" => inventory, "journal_commit" => data.fetch("journal_commit")}
-        end
-
-        def progress(operation:, pane:, generation:, step: nil, report: nil, message: nil)
-          worker!(pane)
-          params = selection.merge("expected_generation" => generation, "pane" => pane)
-          parts = []
-          case operation
-          when "queue_start" then params["step"] = step
-          when "queue_finish"
-            params["step"] = step
-            parts << Files.read_file(report, 65_536)
-          when "queue_fail" then params["message"] = message
-          else raise ArgumentError, "unknown ordinary queue operation"
-          end
-          mutate("progress-#{generation}", operation, params, parts)
-        end
-
-        def submit(pane:, generation:, receipt:, artifacts: [])
-          worker!(pane)
-          bytes = Files.read_file(receipt, 16_384)
-          value = JSON.parse(bytes)
-          unless value.values_at("project_id", "assignment_id", "attempt_id", "scope") ==
-              context.values_at("project_id", "assignment_id", "attempt_id", "scope") &&
-              value.fetch("artifacts").size == artifacts.size
-            raise ArgumentError, "result receipt differs from ordinary selection"
-          end
-          parts = artifacts.each_with_index.map do |file, index|
-            content = Files.read_file(file, Authority::TransferCodec::LIMITS.fetch(:receipt_artifacts).last)
-            unless Digest::SHA256.hexdigest(content) == value.fetch("artifacts").fetch(index).fetch("sha256")
-              raise ArgumentError, "result artifact differs from its receipt"
-            end
-            content
-          end
-          params = selection.merge("expected_generation" => generation,
-            "pane" => pane, "head" => value.fetch("head"), "receipt_sha256" => Digest::SHA256.hexdigest(bytes))
-          verify_result_intent!(params, [bytes] + parts)
-          observed = status
-          if (accepted = observed.fetch("submitted_result"))
-            # An accepted result may have lost its reply. Its generation selects
-            # the original input; never mint a replacement mutation to recover it.
-            original_generation = accepted.fetch("generation") - 1
-            input = File.join(@root, "requests", "result-#{original_generation}", "request.json")
-            original = Files.json(input)
-            expected = document("submit_result", params.merge("expected_generation" => original_generation), nil,
-              inventory([bytes] + parts))
-            unless original.except("mutation_id") == expected.except("mutation_id")
-              raise ArgumentError, "accepted result differs from retained original input"
-            end
-            return replay(input: input).merge("request" => input)
-          end
-          unless observed.fetch("state") == "running" && observed.fetch("generation") == generation
-            raise AttemptErrors::EvidenceUnavailable, "result requires the current canonical generation; retain original inputs"
-          end
-          reply = mutate("result-#{generation}", "submit_result", params, [bytes] + parts)
-          signal_result(reply.fetch("data"))
-          reply
-        end
-
-        def adopt(pane:)
-          owner = supervisor
-          raise ArgumentError, "ordinary result owner pane differs" unless pane == owner.fetch("binding").fetch("pane")
-          observed = status
-          return {"status" => "ok", "data" => observed} if %w[succeeded failed].include?(observed.fetch("state"))
-          result = observed.fetch("submitted_result")
-          raise AttemptErrors::EvidenceUnavailable, "ordinary worker has not submitted a result" unless result
-          mutate("adopt-#{owner.fetch('generation')}-#{observed.fetch('generation')}", "finish", selection.merge("pane" => pane,
-            "expected_generation" => observed.fetch("generation"),
-            **result.slice("result_id", "receipt_digest", "head")))
-        end
-
-        def replay(input:)
-          request = Files.json(input)
-          expected = request["operation"] == "adopt_supervisor" ? context.slice("assignment_id") : selection
-          unless request["project_id"] == context.fetch("project_id") &&
-              request.fetch("params").slice("assignment_id", "attempt_id") == expected &&
-              File.dirname(File.dirname(File.expand_path(input))) == File.join(@root, "requests")
-            raise ArgumentError, "recovery request differs from original execution"
-          end
-          reply = @transport.request(input: input)
-          signal_result(reply.fetch("data")) if request.fetch("operation") == "submit_result"
-          reply
-        end
-
-        private
-
-        def selection = context.slice("assignment_id", "attempt_id")
-
-        # A filesystem watch hint is neither execution state nor a receipt.
-        # Adoption never reads this file, even after restart or forged writes.
-        def signal_result(result)
-          name = "hint-#{SecureRandom.hex(8)}"
-          Files.write_file(@root, name, JSON.generate({"hint_only" => true,
-            "project_id" => context.fetch("project_id"), **selection,
-            "result_id" => result.fetch("result_id")}))
-          File.rename(File.join(@root, name), File.join(@root, "result-hint.json"))
-          File.open(@root) { |file| file.fsync }
-        ensure
-          File.unlink(File.join(@root, name)) if name && File.exist?(File.join(@root, name))
-        end
-
-        def worker!(pane)
-          raise ArgumentError, "ordinary worker pane differs" unless pane == context.fetch("pane")
-        end
-
-        def step(value)
-          value && {"number" => value.number, "name" => value.name, "status" => value.status.to_s,
-            "instructions" => value.instructions, "workflow" => value.workflow, "skill" => value.skill}
-        end
-
-        def read(operation, params)
-          Dir.mktmpdir("ordinary-read-", @root) do |directory|
-            Files.write_file(directory, "request.json", JSON.generate(document(operation, params, nil, [])))
-            @transport.request(input: File.join(directory, "request.json"))
-          end
-        end
-
-        def snapshot(operation, params)
-          Dir.mktmpdir("ordinary-read-", @root) do |directory|
-            Files.write_file(directory, "request.json", JSON.generate(document(operation, params, nil, [])))
-            reply = @transport.request(input: File.join(directory, "request.json"), output: File.join(directory, "snapshot"))
-            entries = reply.fetch("files")
-            raise AttemptErrors::EvidenceUnavailable, "canonical queue snapshot count differs" unless entries.one?
-            [reply, Files.read_file(entries.first.fetch("file"), Authority::PreparedWork::MAX_TOTAL)]
-          end
-        end
-
-        def mutate(key, operation, params, parts = [])
-          request = retain(key, operation, params, parts)
-          @transport.request(input: request).merge("request" => request)
-        rescue StandardError => error
-          raise error.class, "#{error.message}; recover original request #{request || key} before new work"
-        end
-
-        def retain(key, operation, params, parts)
-          directory = File.join(@root, "requests")
-          begin
-            Dir.mkdir(directory, 0o700)
-          rescue Errno::EEXIST
-            Authority::PrivateDirectory.verify!(directory)
-          end
-          raise ArgumentError, "ordinary retained operation key is invalid" unless key.match?(/\A[a-z0-9-]{1,128}\z/)
-          File.open(File.join(directory, ".lock"), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
-            lock.flock(File::LOCK_EX)
-            target = File.join(directory, key)
-            value = document(operation, params, nil, inventory(parts))
-            if File.exist?(target)
-              Authority::PrivateDirectory.verify!(target)
-              original = Files.json(File.join(target, "request.json"))
-              unless original.except("mutation_id") == value.except("mutation_id")
-                raise ArgumentError, "retained operation changed; replay its exact request or reconcile canonical state"
-              end
-            else
-              scratch = Dir.mktmpdir(".prepare-", directory)
-              begin
-                parts.each_with_index { |bytes, index| Files.write_file(scratch, "part-#{index}", bytes) }
-                value["mutation_id"] = SecureRandom.hex(16)
-                Files.write_file(scratch, "request.json", JSON.generate(value) + "\n")
-                File.rename(scratch, target)
-                File.open(directory) { |handle| handle.fsync }
-              ensure
-                FileUtils.remove_entry(scratch) if File.exist?(scratch)
-              end
-            end
-            File.join(target, "request.json")
-          end
-        end
-
-        def document(operation, params, mutation, parts)
-          {"version" => 1, "project_id" => context.fetch("project_id"), "operation" => operation,
-            "mutation_id" => mutation, "params" => params, "parts" => parts}
-        end
-
-        def inventory(parts)
-          parts.each_with_index.map { |bytes, index|
-            {"file" => "part-#{index}", "bytes" => bytes.bytesize, "sha256" => Digest::SHA256.hexdigest(bytes)} }
-        end
-
-        def verify_result_intent!(params, parts)
-          expected = document("submit_result", params.except("expected_generation"), nil, inventory(parts))
-          Dir.glob(File.join(@root, "requests", "result-*", "request.json")).each do |input|
-            original = Files.json(input)
-            original = original.merge("params" => original.fetch("params").except("expected_generation"))
-            unless original.except("mutation_id") == expected.except("mutation_id")
-              raise ArgumentError, "result retry changed the retained original intent"
-            end
-          end
-        end
-      end
-    end
-  end
-end