ace-assign 0.63.1 → 0.66.0

data/lib/ace/assign/authority/server.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+require "socket"
+require "fileutils"
+require_relative "deployment"
+require_relative "transfer_codec"
+require_relative "../molecules/evidence_journal"
+
+module Ace
+  module Assign
+    module Authority
+      # Existing assignment owner transport; kernel peers select roles, never argv.
+      class Server
+        CONNECTIONS = 16
+        def initialize(authority_id:, lifecycle:, deployment: Deployment.load,
+          kernel: Ace::Runtime::Molecules::ProtectedLinux.new, composition: "launch", hitl_service: nil)
+          @authority_id, @lifecycle, @deployment, @kernel = authority_id, lifecycle, deployment, kernel
+          @composition = composition
+          @hitl_service = hitl_service
+          deployment.verify_composition!(authority_id, composition: composition)
+          @service = deployment.authority(authority_id)
+          @mutex = Mutex.new
+          @connections = []
+          @handlers = []
+          @transfers = 0
+          @stopped = false
+        end
+
+        def serve
+          @kernel.supported!
+          me = @kernel.capture(Process.pid)
+          unless principal?(me, @service, "uid", "gid", "groups")
+            raise AttemptErrors::UnauthorizedIdentity, "listener principal differs from installed authority"
+          end
+          @deployment.verify_receiver_paths!(@authority_id)
+          directory = File.dirname(@service.fetch("socket_path"))
+          wire.root_path!(directory, directory: true, owner: @service.fetch("uid"))
+          lock = File.open(File.join(directory, "listener.lock"), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+          unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+            raise AttemptErrors::Conflict, "assignment authority already owns its listener"
+          end
+          start_hitl_service!
+          path = @service.fetch("socket_path")
+          if File.exist?(path) || File.symlink?(path)
+            raise AttemptErrors::Conflict, "existing authority endpoint requires verified installer recovery"
+          end
+          @listener = UNIXServer.new(path)
+          File.chmod(0o660, path)
+          @endpoint = wire.socket_identity(path)
+          until @stopped
+            if @hitl_thread && !@hitl_thread.alive?
+              raise Ace::Runtime::RuntimeUnavailableError, "protected HITL boundary stopped before its authority"
+            end
+            ready = IO.select([@listener], nil, nil, 0.25)
+            next unless ready
+            socket = @listener.accept_nonblock(exception: false)
+            next if socket == :wait_readable
+            admitted = @mutex.synchronize do
+              if @connections.size < CONNECTIONS
+                @connections << socket
+                true
+              end
+            end
+            unless admitted
+              refusal(socket, "busy")
+              socket.close
+              next
+            end
+            @mutex.synchronize do
+              @handlers.reject! { |handler| !handler.alive? }
+              @handlers << Thread.new(socket) { |connection| receive(connection) }
+            end
+          end
+        rescue IOError, Errno::EBADF
+          raise unless @stopped
+        ensure
+          stop
+          stop_hitl_service!
+          # Closing a stream does not cancel a handler already inside dispatch.
+          # The owner lock and endpoint remain held until every handler ends.
+          @mutex.synchronize { @handlers.dup }.each(&:join)
+          @lifecycle.close if @endpoint && @lifecycle.respond_to?(:close)
+          if @endpoint && same_endpoint?(path)
+            File.unlink(path)
+          end
+          lock&.close
+        end
+
+        def request_stop
+          @stopped = true
+        end
+
+        def stop
+          @stopped = true
+          @listener&.close unless @listener&.closed?
+          @mutex.synchronize { @connections.each { |socket| socket.close unless socket.closed? } }
+        end
+
+        private
+
+        # The existing HITL boundary is a sibling owned by this listener's
+        # lifetime. It must be ready before assignment ingress is opened.
+        def start_hitl_service!
+          return unless @hitl_service
+          ready = Queue.new
+          @hitl_thread = Thread.new do
+            @hitl_service.run(on_ready: -> { ready << :ready })
+          rescue Exception => error
+            @hitl_failure = error
+            ready << error
+          end
+          @hitl_thread.report_on_exception = false
+          result = ready.pop(timeout: 5)
+          raise Ace::Runtime::RuntimeUnavailableError, "protected HITL boundary startup timed out" if result.nil?
+          raise result if result.is_a?(Exception)
+        end
+
+        def stop_hitl_service!
+          return unless @hitl_thread
+          @hitl_service.stop
+          @hitl_thread.join
+        end
+
+        def same_endpoint?(path)
+          wire.socket_identity(path) == @endpoint
+        rescue StandardError
+          false
+        end
+
+        def receive(socket)
+          deadline = wire.deadline(30)
+          peer = @kernel.peer(socket)
+          frame = wire.read(socket, deadline: [deadline, wire.deadline(5)].min, with_size: true)
+          request = frame.fetch(:data)
+          unless request.is_a?(Hash) && request.keys.sort == %w[mutation_id operation params project_id version] &&
+              request["version"].is_a?(Integer) && request["version"] == 1 && request["operation"].is_a?(String) && request["params"].is_a?(Hash)
+            raise ArgumentError, "invalid authority envelope"
+          end
+          deadline = wire.deadline(90) if %w[reserve_attempt close_execution_scope stop_attempt].include?(request.fetch("operation"))
+          params = request.fetch("params")
+          map = @deployment.verify!(params.fetch("mapping_id"), kernel: @kernel, authority_state: true)
+          unless map["authority_id"] == @authority_id && map["project_id"] == request["project_id"]
+            raise AttemptErrors::UnauthorizedIdentity, "mapping belongs to another authority or project"
+          end
+          project = @deployment.project(map.fetch("project_id"))
+          owner_contexts = project.fetch("inbox_contexts", {}).select do |_id, context|
+            context.fetch("native_mapping_id") == params.fetch("mapping_id") &&
+              context.fetch("owner_credentials").values_at("uid", "gid", "groups") == peer.values_at("uid", "gid", "groups")
+          end
+          context_query = %w[inbox_context_original].include?(request["operation"])
+          if context_query || !owner_contexts.empty?
+            unless context_query && @composition == "services" && request["mutation_id"].nil? &&
+                owner_contexts.key?(params.fetch("inbox_context_id")) && frame.fetch(:bytesize) <= 16_384
+              raise AttemptErrors::UnauthorizedIdentity, "context owner is exclusive to its fixed read-only inbox queries"
+            end
+            role = :context_owner
+          end
+          if request["operation"] == "native_readiness"
+            unless @composition == "launch" && request["mutation_id"].nil? && params.keys == ["mapping_id"] &&
+                frame.fetch(:bytesize) <= 16_384
+              raise ArgumentError, "private readiness envelope differs"
+            end
+            admitted_transfer = @mutex.synchronize do
+              if @transfers < 2
+                @transfers += 1
+                true
+              end
+            end
+            raise AttemptErrors::Conflict, "readiness transfer capacity is busy" unless admitted_transfer
+            @lifecycle.native_readiness!(mapping_id: params.fetch("mapping_id"), peer: peer, socket: socket,
+              codec: transfer_codec, deadline: wire.deadline(10))
+            return
+          end
+          role ||= if principal?(peer, map, "launcher_uid", "launcher_gid", "launcher_groups")
+            :launcher
+          elsif principal?(peer, map, "worker_uid", "worker_gid", "worker_groups")
+            :worker
+          end
+          unless role
+            project = @deployment.project(map.fetch("project_id"))
+            configured = project.fetch("peer_credentials")[peer.fetch("uid").to_s]
+            if configured && peer["gid"] == configured["gid"] && peer["groups"] == configured["groups"]
+              {reviewer: "reviewer_uids", executor: "service_executor_uids", supervisor: "supervisor_uids"}.each do |candidate, key|
+                role ||= candidate if project.fetch(key).include?(peer.fetch("uid"))
+              end
+            end
+          end
+          raise AttemptErrors::UnauthorizedIdentity, "unmapped kernel peer" unless role
+          if request["operation"] == "launch_control"
+            raise AttemptErrors::UnauthorizedIdentity, "Private launcher control requires launcher peer" unless role == :launcher
+            raise ArgumentError, "Private launcher header is oversized" unless frame.fetch(:bytesize) <= 16_384
+            @lifecycle.serve_launch_control!(request: request, peer: peer, socket: socket, codec: transfer_codec, deadline: deadline)
+            return
+          end
+          if %w[bind_inbox finish recover request_review review_status launch_review_intent cancel_review evidence_fetch assignment_inventory observe_execution_scope close_execution_scope stop_attempt prompt_status launch_input_inhibit_selection launch_input_inhibit_completion launch_prompt_intent launch_prompt_completion claim_service_settlement workspace_prune_preview_context].include?(request["operation"]) ||
+              @composition == "services" && %w[attempt_status inbox_context_original].include?(request["operation"])
+            raise ArgumentError, "review control header is oversized" if %w[request_review review_status cancel_review launch_review_intent].include?(request["operation"]) && frame.fetch(:bytesize) > 16_384
+            bodyless_read!(socket, deadline)
+          end
+          if request["operation"] == "gate_ready"
+            raise AttemptErrors::UnauthorizedIdentity, "gate readiness requires worker peer" unless role == :worker
+            @lifecycle.gate_ready(request: request, peer: peer, socket: socket, deadline: deadline)
+          else
+            Molecules::EvidenceJournal.with_event_read_operation do
+              binding = @lifecycle.transfer_binding(request) if @lifecycle.respond_to?(:transfer_binding)
+              if binding
+                raise AttemptErrors::UnauthorizedIdentity, "transfer role differs" unless binding.fetch(:roles).include?(role)
+                raise ArgumentError, "transfer control header is oversized" if frame.fetch(:bytesize) > 16_384
+                @lifecycle.authorize_transfer!(request: request, peer: peer, role: role)
+                admitted_transfer = @mutex.synchronize do
+                  if @transfers < 2
+                    @transfers += 1
+                    true
+                  end
+                end
+                raise AttemptErrors::Conflict, "transfer capacity is busy" unless admitted_transfer
+                codec = transfer_codec
+                if binding.fetch(:direction) == :upload
+                  result = codec.receive(socket, descriptor: params.fetch("transfer"), purpose: binding.fetch(:purpose), deadline: deadline) do |input|
+                    @lifecycle.dispatch(request: request, peer: peer, role: role, transfer: input)
+                  end
+                else
+                  result = @lifecycle.dispatch(request: request, peer: peer, role: role)
+                  parts = result.fetch(:transfer_parts)
+                  descriptor = codec.descriptor(parts, purpose: binding.fetch(:purpose))
+                  result = result.merge(data: result.fetch(:data).merge("transfer" => descriptor))
+                end
+              else
+                raise ArgumentError, "unexpected transfer descriptor" if params.key?("transfer")
+                result = @lifecycle.dispatch(request: request, peer: peer, role: role)
+              end
+              wire.write(socket, {"status" => "ok", "data" => result.fetch(:data),
+                "transport" => {"replayed" => result.fetch(:replayed, false)}}, deadline: deadline, limit: 16_384)
+              if binding && binding.fetch(:direction) == :download
+                codec.send(socket, parts: parts, descriptor: descriptor, purpose: binding.fetch(:purpose), deadline: deadline)
+              end
+            end
+          end
+        rescue ArgumentError, KeyError, AttemptErrors::MalformedTransfer
+          refusal(socket, "invalid_input")
+        rescue AttemptErrors::UnauthorizedIdentity, SecurityError
+          refusal(socket, "unauthorized")
+        rescue AttemptErrors::Conflict
+          refusal(socket, "conflict")
+        rescue AttemptErrors::NotFound
+          refusal(socket, "missing")
+        rescue AttemptErrors::BoundedResultUnavailable
+          refusal(socket, "bounded_result")
+        rescue StandardError
+          refusal(socket, "evidence_unavailable")
+        ensure
+          socket.close unless socket.closed?
+          @mutex.synchronize do
+            @connections.delete(socket)
+            @transfers -= 1 if admitted_transfer
+          end
+        end
+
+        # These closed read operations have no request body. Half-close proves
+        # framing completion before status or artifact data can be exposed.
+        def bodyless_read!(socket, deadline)
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise ArgumentError, "read request framing is incomplete" unless remaining.positive? && IO.select([socket], nil, nil, remaining)
+            bytes = socket.read_nonblock(1, exception: false)
+            next if bytes == :wait_readable
+            raise ArgumentError, "unexpected read request body" unless bytes.nil?
+            return
+          end
+        end
+
+        def transfer_codec
+          @mutex.synchronize do
+            @transfer_codec ||= begin
+              root = @service.fetch("state_root")
+              PrivateDirectory.verify!(root)
+              spool = File.join(root, "transfers")
+              Dir.mkdir(spool, 0o700) unless File.exist?(spool) || File.symlink?(spool)
+              TransferCodec.new(root: spool)
+            end
+          end
+        end
+
+        def principal?(identity, mapping, uid, gid, groups)
+          identity["uid"] == mapping[uid] && identity["gid"] == mapping[gid] && identity["groups"] == mapping[groups]
+        end
+
+        def refusal(socket, code)
+          wire.write(socket, {"status" => "error", "error" => {"code" => code, "message" => "Protected authority refused #{code}"}},
+            deadline: wire.deadline(0.1))
+        rescue StandardError
+          nil
+        end
+
+        def wire
+          Ace::Runtime::Molecules::ProtectedSocket
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/authority/service_cleanup_dispatch.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Authority
+      # Canonical-only original dispatch proof shared by status, root admission
+      # and initial/retained inspection imports. Installed peer policy stays in
+      # the fixed root transport owner.
+      module ServiceCleanupDispatch
+        CLEANUP_MUTABLE_SETTLEMENT_FIELDS = %w[state receipt reason claimed_at failed_at no_effect_challenge
+          challenge_generation challenge_event_digest completion_digest no_effect_completion_digest].freeze
+
+        def cleanup_dispatch_context!(record, commit:, selectors: nil, pending: nil)
+          unless @journal.evidence_mode == :protected &&
+              record.values_at("operation", "dispatch_phase") == ["prune-preserved-workspace", "dispatch_started"]
+            raise AttemptErrors::EvidenceUnavailable, "cleanup original dispatch is unavailable"
+          end
+          pending ||= {commit: commit}
+          @journal.verify_canonical_prefix!(commit: commit) unless service_read_view(pending)
+          # The existing index authenticates accepted record provenance without
+          # recursively asking this terminal collection to validate itself.
+          selected = @journal.service_request_records(commit: commit)
+            .select { |entry| entry["request_id"] == record.fetch("request_id") }
+          # Initial import receives the lower writer's proposed terminal
+          # replacement. Its settlement fields are validated by that writer
+          # and collection; the original immutable dispatch must still match.
+          unless selected.one? && selected.first.except(*CLEANUP_MUTABLE_SETTLEMENT_FIELDS) ==
+              record.except(*CLEANUP_MUTABLE_SETTLEMENT_FIELDS)
+            raise AttemptErrors::EvidenceUnavailable, "cleanup selected record differs"
+          end
+          context(record, pending: {commit: commit})
+          events = service_read_events(record, pending)
+          names = %w[request_event_digest dispatch_event_digest]
+          operations = %w[request_service begin_dispatch]
+          if selectors.nil?
+            selectors = names.zip(operations).to_h do |name, operation|
+              matches = events.select do |event|
+                event["type"] == "authority_mutation" && event.dig("payload", "operation") == operation &&
+                  event.dig("payload", "data", "request_id") == record.fetch("request_id") &&
+                  event.dig("payload", "data", "claim_binding") == record.fetch("claim_binding") &&
+                  event.dig("payload", "data", operation == "request_service" ? "claim" : "invocation") ==
+                    (operation == "request_service" ? "created" : "permitted")
+              end
+              raise AttemptErrors::EvidenceUnavailable, "cleanup original acceptance is ambiguous" unless matches.one?
+              [name, matches.first.fetch("digest")]
+            end
+          end
+          unless selectors.is_a?(Hash) && selectors.keys.sort == names.sort &&
+              selectors.values.all? { |value| value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/) } && selectors.values.uniq.size == 2
+            raise AttemptErrors::EvidenceUnavailable, "cleanup original acceptance selectors differ"
+          end
+          introductions = service_read_introductions(record, selectors.values, pending)
+          dispatch_record = nil
+          names.zip(operations).each do |name, operation|
+            selector = selectors.fetch(name)
+            matches = events.select { |event| event.fetch("digest") == selector }
+            event = matches.one? && matches.first
+            payload = event && event.fetch("payload")
+            unless event && event.fetch("type") == "authority_mutation" && payload.fetch("operation") == operation &&
+                payload.slice("assignment_id", "attempt_id") == record.slice("assignment_id", "attempt_id") &&
+                payload.fetch("data").slice("request_id", "claim_binding") == record.slice("request_id", "claim_binding") &&
+                payload.fetch("data").fetch(operation == "request_service" ? "claim" : "invocation") ==
+                  (operation == "request_service" ? "created" : "permitted")
+              raise AttemptErrors::EvidenceUnavailable, "cleanup original acceptance differs"
+            end
+            prefix = @journal.read_events(record.fetch("assignment_id"), commit: introductions.fetch(selector))
+              .select { |entry| entry.fetch("attempt_id") == record.fetch("attempt_id") }
+            original = @journal.service_request(record.fetch("request_id"), commit: introductions.fetch(selector))
+            expected = operation == "request_service" ? original&.merge("dispatch_phase" => "dispatch_started",
+              "operation_owner_binding" => record.fetch("operation_owner_binding"),
+              "executor_process_binding" => record.fetch("executor_process_binding")) : original
+            unless expected&.except(*CLEANUP_MUTABLE_SETTLEMENT_FIELDS) == record.except(*CLEANUP_MUTABLE_SETTLEMENT_FIELDS) &&
+                prefix.last == event && prefix[-2] &&
+                prefix[-2].fetch("type") == (operation == "request_service" ? "service_claim" : "service_transition") &&
+                prefix[-2].dig("payload", "record_digest") == Atoms::EvidenceDigest.digest(original) &&
+                event.fetch("previous_digest") == prefix[-2].fetch("digest")
+              raise AttemptErrors::EvidenceUnavailable, "cleanup acceptance is not its original canonical introduction"
+            end
+            dispatch_record = original if operation == "begin_dispatch"
+          end
+          freeze_projection(JSON.parse(JSON.generate(selectors.merge("commit" => commit, "dispatch_record" => dispatch_record))))
+        rescue KeyError, TypeError, ArgumentError
+          raise AttemptErrors::EvidenceUnavailable, "cleanup original dispatch proof is incomplete"
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/authority/service_cleanup_evidence.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "ace/runtime/molecules/protected_artifact_set"
+require_relative "cleanup_result_protection"
+
+module Ace
+  module Assign
+    module Authority
+      # The existing service evidence owner authenticates this complete pair.
+      # Root-private archives remain outside the authority evidence graph.
+      module ServiceCleanupEvidence
+        ROOT_SELECTION_SCHEMA = "ace.protected-workspace-prune-root-selection/v1"
+        ROOT_RECEIPT_SCHEMA = "ace.protected-workspace-prune-receipt/v1"
+        ROOT_SELECTION_FIELDS = %w[schema request_id input_digest operation_owner_binding_digest receipt_ref].freeze
+        ROOT_INSPECTION_SELECTION_SCHEMA = "ace.protected-workspace-prune-inspection-selection/v1"
+        ROOT_INSPECTION_SELECTION_FIELDS = %w[schema request_id input_digest operation_owner_binding_digest inspection_ref].freeze
+        ROOT_RECEIPT_FIELDS = %w[schema request_id input_digest maintenance target publication canonical_snapshots preservation removal].freeze
+
+        # Pre-import decoding reuses the collection validator. Only the lower
+        # writer's pending collection can authenticate protected storage and
+        # accept a terminal update.
+        def cleanup_inspection_inputs!(contents, record, challenge)
+          unless record["operation"] == "prune-preserved-workspace" && contents.is_a?(Array) && contents.size == 2
+            raise AttemptErrors::ReceiptRejected, "cleanup inspection requires its complete pair"
+          end
+          cleanup_documents!(contents, record, no_effect: true, challenge: challenge)
+          true
+        rescue KeyError, TypeError, JSON::ParserError, JSON::GeneratorError
+          raise AttemptErrors::ReceiptRejected, "cleanup inspection pair is unavailable"
+        end
+
+        private
+
+        def cleanup_collection!(references, record, state, pending)
+          unless record["operation"] == "prune-preserved-workspace" && %w[succeeded failed-settled].include?(state) && references.size == 2
+            raise AttemptErrors::ReceiptRejected, "cleanup completion requires its complete original evidence pair"
+          end
+          no_effect = state == "failed-settled"
+          challenge = no_effect ? challenge!(record, pending: pending) : nil
+          expected = no_effect ? context_for_challenge(record, challenge) : context(record)
+          proof = cleanup_dispatch_context!(record, commit: pending && pending[:commit] || @journal.ref_value, pending: pending)
+          contents = references.map do |reference|
+            if pending && pending[:pending_events]
+              @canonical.read_pending(reference, **expected, **pending.slice(:current_events, :pending_events, :blobs, :commit))
+            else
+              @canonical.read(reference, **expected, commit: pending && pending[:commit] || @journal.ref_value)
+            end
+          end
+          reference, operation_bytes = cleanup_documents!(contents, record, no_effect: no_effect,
+            challenge: challenge)
+          path = reference.fetch("path")
+          # The lower writer supplies its pending import transaction. Historical
+          # consumers have only a pinned commit and never reopen mutable storage.
+          if pending && pending[:pending_events]
+            selected_artifacts = @cleanup_artifacts || Ace::Runtime::Molecules::ProtectedArtifactSet.new(
+              protection: CleanupResultProtection.new(result_path: path, authority_gid: Process.egid))
+            selected_artifacts.with do |artifacts|
+              unless artifacts.read!(reference) == operation_bytes
+                raise AttemptErrors::ReceiptRejected, "cleanup retained result bytes differ"
+              end
+              artifacts.verify_unchanged!
+            end
+          end
+          if (view = service_read_view(pending))
+            view.projection = settlement_projection(record, pending, challenge, proof)
+          end
+          contents.freeze
+        rescue KeyError, TypeError, JSON::ParserError, JSON::GeneratorError, Ace::Runtime::RuntimeUnavailableError
+          raise AttemptErrors::ReceiptRejected, "cleanup original evidence is unavailable"
+        end
+
+        def cleanup_documents!(contents, record, no_effect:, challenge:)
+          documents = contents.map { |bytes| cleanup_json!(bytes) }
+          selection_schema = no_effect ? ROOT_INSPECTION_SELECTION_SCHEMA : ROOT_SELECTION_SCHEMA
+          selection_fields = no_effect ? ROOT_INSPECTION_SELECTION_FIELDS : ROOT_SELECTION_FIELDS
+          selection_index = documents.each_index.select { |index| documents[index]["schema"] == selection_schema }
+          receipt_index = documents.each_index.select do |index|
+            no_effect ? documents[index].keys.sort == ServiceEvidence::INSPECTION_FIELDS.sort : documents[index]["schema"] == ROOT_RECEIPT_SCHEMA
+          end
+          unless selection_index.one? && receipt_index.one?
+            raise AttemptErrors::ReceiptRejected, "cleanup original evidence selection is ambiguous"
+          end
+          selection = documents.fetch(selection_index.first)
+          receipt = documents.fetch(receipt_index.first)
+          closed_cleanup!(selection, selection_fields)
+          closed_cleanup!(receipt, no_effect ? ServiceEvidence::INSPECTION_FIELDS : ROOT_RECEIPT_FIELDS)
+          unless [selection, receipt].all? { |value| value["request_id"] == record.fetch("request_id") && value["input_digest"] == record.fetch("input_digest") } &&
+              selection["operation_owner_binding_digest"] == Atoms::EvidenceDigest.digest(record.fetch("operation_owner_binding"))
+            raise AttemptErrors::ReceiptRejected, "cleanup original owner or request differs"
+          end
+          reference = selection.fetch(no_effect ? "inspection_ref" : "receipt_ref")
+          closed_cleanup!(reference, %w[path bytes sha256])
+          path = reference.fetch("path")
+          operation_bytes = contents.fetch(receipt_index.first)
+          unless path.is_a?(String) && path.bytesize <= 4096 && path.valid_encoding? && !path.include?("\0") &&
+              path.start_with?("/") && File.expand_path(path) == path &&
+              reference["bytes"].is_a?(Integer) && reference["bytes"].between?(1, 65_536) &&
+              reference["bytes"] == operation_bytes.bytesize && reference["sha256"] == Digest::SHA256.hexdigest(operation_bytes)
+            raise AttemptErrors::ReceiptRejected, "cleanup retained result reference differs"
+          end
+          if no_effect
+            inspection_projection!(receipt, record, challenge)
+          else
+            cleanup_receipt_projection!(receipt, record)
+          end
+          [reference, operation_bytes]
+        end
+
+        def cleanup_json!(bytes)
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, 65_536)
+            raise AttemptErrors::ReceiptRejected, "cleanup evidence exceeds bounds"
+          end
+          text = bytes.dup.force_encoding(Encoding::UTF_8)
+          raise AttemptErrors::ReceiptRejected, "cleanup evidence is invalid UTF8" unless text.valid_encoding? && !text.include?("\0")
+          value = JSON.parse(text, create_additions: false, max_nesting: 16, allow_duplicate_key: false, allow_comments: false)
+          raise AttemptErrors::ReceiptRejected, "cleanup evidence is not an object" unless value.is_a?(Hash)
+          value
+        end
+
+        def closed_cleanup!(value, fields)
+          unless value.is_a?(Hash) && value.keys.sort == fields.sort
+            raise AttemptErrors::ReceiptRejected, "cleanup evidence fields differ"
+          end
+        end
+
+        def cleanup_receipt_projection!(receipt, record)
+          preservation = receipt.fetch("preservation")
+          closed_cleanup!(preservation, %w[head branch destinations manifest_sha256 inventory_sha256 file_count total_bytes private_manifest_sha256 archives_sha256])
+          unless preservation["file_count"].is_a?(Integer) && preservation["file_count"].between?(0, 4096) &&
+              preservation["total_bytes"].is_a?(Integer) && preservation["total_bytes"].between?(0, 256 * 1024 * 1024) &&
+              %w[manifest_sha256 inventory_sha256 private_manifest_sha256 archives_sha256].all? { |key| cleanup_sha?(preservation[key]) } &&
+              preservation.values_at("manifest_sha256", "inventory_sha256", "private_manifest_sha256").uniq.one?
+            raise AttemptErrors::ReceiptRejected, "cleanup preservation observation differs"
+          end
+          input = receipt.slice("maintenance", "target", "publication").merge("schema" => "ace.protected-workspace-prune/v1",
+            "preservation" => preservation.slice("head", "branch", "destinations", "manifest_sha256"))
+          unless Atoms::EvidenceDigest.digest(input) == record.fetch("input_digest") &&
+              receipt.fetch("maintenance") == record.slice("project_id", "mapping_id", "assignment_id", "attempt_id")
+            raise AttemptErrors::ReceiptRejected, "cleanup original input differs"
+          end
+          snapshots = receipt.fetch("canonical_snapshots")
+          unless snapshots.is_a?(Array) && snapshots.size.between?(1, 256)
+            raise AttemptErrors::ReceiptRejected, "cleanup canonical snapshots exceed bounds"
+          end
+          snapshots.each do |snapshot|
+            closed_cleanup!(snapshot, %w[mapping_id journal_commit binding_event_digest release_event_digest proof_event_digest])
+            unless snapshot["mapping_id"].is_a?(String) && snapshot["mapping_id"].match?(Molecules::JournalMutation::ID) &&
+                snapshot["journal_commit"].is_a?(String) && snapshot["journal_commit"].match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/) &&
+                %w[binding_event_digest release_event_digest proof_event_digest].all? { |key| cleanup_sha?(snapshot[key]) }
+              raise AttemptErrors::ReceiptRejected, "cleanup canonical snapshot differs"
+            end
+          end
+          ids = snapshots.map { |snapshot| snapshot.fetch("mapping_id") }
+          raise AttemptErrors::ReceiptRejected, "cleanup canonical snapshots are not uniquely ordered" unless ids == ids.uniq.sort
+          removal = receipt.fetch("removal")
+          closed_cleanup!(removal, %w[original captured outcome fence_digest])
+          unless removal["outcome"] == "removed" && cleanup_sha?(removal["fence_digest"])
+            raise AttemptErrors::ReceiptRejected, "cleanup has no positive removal observation"
+          end
+          %w[original captured].each do |key|
+            object = removal.fetch(key)
+            closed_cleanup!(object, %w[device inode worktree_admin_id head branch])
+            unless %w[device inode].all? { |field| object[field].is_a?(Integer) && object[field].positive? } &&
+                object["worktree_admin_id"].is_a?(String) && object["worktree_admin_id"].bytesize.between?(1, 200) &&
+                object["worktree_admin_id"].match?(/\A[a-zA-Z0-9_.-]+\z/) &&
+                object["head"] == preservation["head"] && object["branch"] == preservation["branch"]
+              raise AttemptErrors::ReceiptRejected, "cleanup captured object differs"
+            end
+          end
+          unless removal.fetch("original") == removal.fetch("captured")
+            raise AttemptErrors::ReceiptRejected, "cleanup replaced object cannot attest removal"
+          end
+          true
+        end
+
+        def cleanup_sha?(value) = value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+      end
+    end
+  end
+end