ace-lab 0.3.1 → 0.5.0

data/lib/ace/lab/organisms/protected_cleanup_owner.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+require "ace/runtime/molecules/protected_socket"
+require "ace/runtime/molecules/protected_artifact_set"
+require "ace/assign/authority/transfer_codec"
+require_relative "../molecules/protected_cleanup_owner_admission"
+
+module Ace
+  module Lab
+    module Organisms
+      # The immutable direct root entry supplies all collaborators. Durable
+      # request/outcome authority stays in its original canonical journal and
+      # Installer's retained physical result, never this transport owner.
+      class ProtectedCleanupOwner
+        Wire = Ace::Runtime::Molecules::ProtectedSocket
+        Client = Molecules::ProtectedCleanupOwnerClient
+        MAX_RETAINED = 256
+        MAX_CONNECTIONS = 16
+
+        def initialize(observer:, admission:, snapshots:, journals:, kernel:, installer:, scratch_root:,
+          protection: Ace::Runtime::Molecules::ProtectedArtifactSet::Protection.new)
+          @observer, @admission, @snapshots, @journals = observer, admission, snapshots, journals
+          @kernel, @installer = kernel, installer
+          @protection = protection
+          @codec = Ace::Assign::Authority::TransferCodec.new(root: scratch_root)
+          @lock, @consumed = Mutex.new, {}
+          @connections, @changed = [], ConditionVariable.new
+          @stopping = false
+        end
+
+        # Only the trusted fixed entry supplies the installed connection group.
+        # Endpoint and lock paths remain source constants, never request inputs.
+        def serve(connect_gid:)
+          @admission.connection_group!(connect_gid)
+          @observer.observe_self!(deadline: Wire.deadline(5))
+          path = Client::PATH
+          parent = File.dirname(path)
+          Wire.root_path!(parent, directory: true)
+          parents = hold_parent!(parent)
+          parent_stat = File.lstat(parent)
+          unless parent_stat.directory? && parent_stat.uid == Process.uid && parent_stat.gid == connect_gid && (parent_stat.mode & 0o7777) == 0o2750
+            raise SecurityError, "cleanup listener parent differs"
+          end
+          parent_identity = [parent_stat.dev, parent_stat.ino]
+          lifetime = File.open("#{path}.lock", File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600)
+          lifetime.close_on_exec = true
+          stat = lifetime.stat
+          unless stat.file? && stat.uid == Process.uid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise SecurityError, "cleanup lifetime lock differs"
+          end
+          @protection.verify!("#{path}.lock", lifetime, directory: false)
+          raise SecurityError, "cleanup lifetime lock path changed" unless file_identity(File.lstat("#{path}.lock")) == file_identity(lifetime.stat)
+          raise Ace::Runtime::RuntimeUnavailableError, "cleanup listener already active" unless lifetime.flock(File::LOCK_EX | File::LOCK_NB)
+          raise SecurityError, "cleanup lifetime lock path changed after flock" unless file_identity(File.lstat("#{path}.lock")) == file_identity(lifetime.stat)
+          verify_parents!(parents)
+          begin
+            stale = File.lstat(path)
+            unless stale.socket? && stale.uid == Process.uid && stale.gid == connect_gid && (stale.mode & 0o7777) == 0o660
+              raise SecurityError, "cleanup stale endpoint differs"
+            end
+            File.unlink(path)
+          rescue Errno::ENOENT
+            nil
+          end
+          @listener = UNIXServer.new(path)
+          @listener.close_on_exec = true
+          created = File.lstat(path)
+          unless created.socket? && created.uid == Process.uid && created.gid == connect_gid &&
+              [File.lstat(parent).dev, File.lstat(parent).ino] == parent_identity
+            raise SecurityError, "cleanup endpoint creation differs"
+          end
+          endpoint = [created.dev, created.ino, created.uid, created.gid]
+          File.chmod(0o660, path)
+          own = File.lstat(path)
+          unless own.socket? && (own.mode & 0o7777) == 0o660 && [own.dev, own.ino, own.uid, own.gid] == endpoint && [File.lstat(parent).dev, File.lstat(parent).ino] == parent_identity
+            raise SecurityError, "cleanup endpoint publication differs"
+          end
+          published = true
+          until @stopping
+            socket = @listener.accept
+            accepted_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            socket.close_on_exec = true
+            admitted = @lock.synchronize do
+              @connections.reject! { |thread| !thread.alive? }
+              if @connections.size >= MAX_CONNECTIONS
+                false
+              else
+                worker = Thread.new(socket, accepted_at) do |owned_socket, original_acceptance|
+                  begin
+                    verify_parents!(parents)
+                    current = File.lstat(path)
+                    unless current.socket? && (current.mode & 0o7777) == 0o660 && [current.dev, current.ino, current.uid, current.gid] == endpoint
+                      raise SecurityError, "cleanup endpoint changed"
+                    end
+                    handle(owned_socket, accepted_at: original_acceptance)
+                  rescue SecurityError, Ace::Runtime::RuntimeUnavailableError, Ace::Assign::Error, IOError, SystemCallError => error
+                    # Refusal/transport failure closes only this connection.
+                    # Its consumed state, including uncertainty, is preserved.
+                    code = error.is_a?(SecurityError) ? "unauthorized_or_changed_selection" : "unavailable"
+                    warn("cleanup connection refused: #{code}")
+                  ensure
+                    owned_socket.close unless owned_socket.closed?
+                    @lock.synchronize { @changed.broadcast }
+                  end
+                end
+                @connections << worker
+                true
+              end
+            end
+            socket.close unless admitted
+          end
+        rescue IOError, Errno::EBADF
+          raise unless @stopping
+        ensure
+          @listener.close if @listener && !@listener.closed?
+          @lock.synchronize do
+            # Wait for actual callbacks, never mistake a dead callback's
+            # unconfirmed outcome for activity or physical settlement.
+            while @connections.any?(&:alive?) || @consumed.values.any? { |entry| entry[:state] == :invoked }
+              @changed.wait(@lock, 0.1)
+            end
+          end
+          unconfirmed = @lock.synchronize { @consumed.values.any? { |entry| entry[:state] == :unconfirmed } }
+          if endpoint
+            begin
+              verify_parents!(parents)
+              current = File.lstat(path)
+              File.unlink(path) if current.socket? && (!published || (current.mode & 0o7777) == 0o660) && [current.dev, current.ino, current.uid, current.gid] == endpoint
+            rescue Errno::ENOENT
+              nil
+            end
+          end
+          lifetime&.close
+          parents&.each { |entry| entry.fetch(:handle).close }
+          if unconfirmed && $!.nil?
+            raise Ace::Runtime::RuntimeUnavailableError, "cleanup invocation outcome remains unconfirmed after callback termination"
+          end
+        end
+
+        def stop
+          @stopping = true
+          @listener.close if @listener && !@listener.closed?
+        end
+
+        # Listener construction and fixed socket ownership are separately
+        # provisioned; every accepted connection still authenticates its peer.
+        def handle(socket, accepted_at: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+          admission_deadline = accepted_at + 5
+          peer = @kernel.peer(socket)
+          frame = Wire.read(Wire::Ingress.new(socket), deadline: admission_deadline, limit: 65_536)
+          eof!(socket, admission_deadline)
+          original = @observer.observe_self!(deadline: admission_deadline)
+          if frame == {"schema" => Client::SCHEMA, "kind" => "identity"}
+            @admission.identity_reader!(peer)
+            Wire.write(socket, {"schema" => Client::SCHEMA, "kind" => "identity", "operation_owner_binding" => original},
+              deadline: admission_deadline, limit: Client::LIMIT)
+            return
+          end
+          @admission.receiver!(peer)
+          receiver_peer = Atoms::ProtectedWorkspacePruneInput.freeze_value(JSON.parse(JSON.generate(peer)))
+          deadline = frame["kind"] == "preview" ? admission_deadline : accepted_at + 300
+          context = nil
+          @snapshots.call do |snapshot|
+            # Reuse exact immutable event bytes only during this held read.
+            # Peer admission remains fresh; neither the view nor its memo
+            # survives into Installer effects or the next connection.
+            Ace::Assign::Molecules::EvidenceJournal.with_event_read_operation do
+              snapshot.with(deadline: deadline) do |view|
+                context = if frame["kind"] == "preview"
+                  @admission.preview!(frame: frame, peer: peer, operation_owner_binding: original, journal: @journals.call(view))
+                elsif frame["kind"] == "inspect"
+                  @admission.inspect!(frame: frame, peer: peer, operation_owner_binding: original, journal: @journals.call(view))
+                else
+                  @admission.admit!(frame: frame, peer: peer, operation_owner_binding: original, journal: @journals.call(view))
+                end
+              end
+            end
+          end
+          if frame["kind"] == "preview"
+            unless @installer.respond_to?(:preview_cleanup!)
+              raise SecurityError, "same Installer preview producer unavailable"
+            end
+            result = @installer.preview_cleanup!(context: context, receiver_peer: receiver_peer, deadline: deadline)
+            unless Ace::Assign::Atoms::EvidenceDigest.digest(@observer.observe_self!(deadline: deadline)) ==
+                Ace::Assign::Atoms::EvidenceDigest.digest(original)
+              raise SecurityError, "cleanup original owner changed during preview"
+            end
+            result = Ace::Lab::Atoms::ProtectedWorkspacePrunePreview.result!(result,
+              intent: frame.fetch("intent"), context: frame.fetch("maintenance_context"))
+            Wire.write(socket, result, deadline: deadline, limit: Client::LIMIT)
+            return
+          end
+          if frame["kind"] == "inspect"
+            inspection(socket, frame, context, original, deadline, receiver_peer: receiver_peer)
+            return
+          end
+          key = Ace::Assign::Atoms::EvidenceDigest.digest(frame)
+          retained = @lock.synchronize do
+            if (entry = @consumed[context.fetch("record").fetch("request_id")])
+              raise SecurityError, "cleanup original invocation input differs" unless entry.fetch(:key) == key
+              entry
+            else
+              raise Ace::Runtime::RuntimeUnavailableError, "cleanup lifetime capacity unavailable" if @consumed.size >= MAX_RETAINED
+              @consumed[context.fetch("record").fetch("request_id")] = {key: key, state: :invoking}
+            end
+          end
+          result = @lock.synchronize { retained[:result] }
+          unless result
+            authorized = @lock.synchronize do
+              next false unless retained[:state] == :invoking && !retained[:inhibited]
+              retained[:state] = :invoked
+              true
+            end
+            raise Ace::Runtime::RuntimeUnavailableError, "cleanup original result unavailable" unless authorized
+            begin
+              # No canonical/source lock is held over fixed privileged work.
+              unless @observer.observe_self!(deadline: [deadline, Wire.deadline(5)].min) == original
+                raise SecurityError, "cleanup original owner changed before invocation"
+              end
+              result = @installer.execute_cleanup!(context: context, receiver_peer: receiver_peer, deadline: deadline)
+              result = result!(result, frame)
+              @lock.synchronize { retained[:result] = result; retained[:state] = :completed }
+            ensure
+              @lock.synchronize do
+                if retained[:state] == :invoked
+                  retained[:state] = :unconfirmed
+                  retained[:inhibited] = true
+                end
+                @changed.broadcast
+              end
+            end
+          end
+          unless @observer.observe_self!(deadline: [deadline, Wire.deadline(5)].min) == original
+            raise SecurityError, "cleanup original owner changed before result"
+          end
+          ref = result.fetch(:receipt_ref)
+          Wire.write(socket, {"schema" => Client::SCHEMA, "kind" => "result", "request_id" => frame.fetch("request_id"),
+            "input_digest" => frame.fetch("input_digest"), "receipt_ref" => ref}, deadline: deadline, limit: Client::LIMIT)
+          descriptor = @codec.descriptor([result.fetch(:bytes)], purpose: :artifacts)
+          @codec.send(socket, parts: [result.fetch(:bytes)], descriptor: descriptor, purpose: :artifacts, deadline: deadline)
+        ensure
+          socket.close unless socket.closed?
+        end
+
+        private
+
+        def inspection(socket, frame, context, original, deadline, receiver_peer:)
+          original_owner = Ace::Assign::Atoms::EvidenceDigest.digest(context.fetch("record").fetch("operation_owner_binding")) ==
+            Ace::Assign::Atoms::EvidenceDigest.digest(original)
+          if original_owner
+            executable = frame.except("challenge_ref").merge("kind" => "execute")
+            key = Ace::Assign::Atoms::EvidenceDigest.digest(executable)
+            @lock.synchronize do
+              request = context.fetch("record").fetch("request_id")
+              retained = @consumed[request]
+              if retained
+                raise SecurityError, "cleanup original inspection input differs" unless retained.fetch(:key) == key
+              else
+                raise Ace::Runtime::RuntimeUnavailableError, "cleanup lifetime capacity unavailable" if @consumed.size >= MAX_RETAINED
+                retained = @consumed[request] = {key: key, state: :inhibited}
+              end
+              retained[:inhibited] = true
+              retained[:state] = :inhibited if retained[:state] == :invoking
+              while retained[:state] == :invoked
+                remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                raise Ace::Runtime::RuntimeUnavailableError, "cleanup original effect remains unconfirmed" unless remaining.positive?
+                @changed.wait(@lock, remaining)
+              end
+            end
+            # This is callback inhibition only. Child/writer/physical absence
+            # still requires the actual domain inspector's independent proof.
+            inhibition = {"operation_owner_binding_digest" => frame.fetch("operation_owner_binding_digest"),
+              "dispatch_event_digest" => frame.fetch("dispatch_event_digest"), "state" => "inhibited", "pending_effects" => 0}
+            context = Atoms::ProtectedWorkspacePruneInput.freeze_value(context.merge("input_inhibition" => inhibition))
+          end
+          unless @observer.observe_self!(deadline: [deadline, Wire.deadline(5)].min) == original
+            raise SecurityError, "cleanup readback owner changed before inspection"
+          end
+          inspected = @installer.inspect_cleanup!(context: context, receiver_peer: receiver_peer, deadline: deadline)
+          unless inspected.is_a?(Hash) && inspected.keys.sort == %i[bytes kind receipt_ref] &&
+              %w[succeeded failed-no-effect].include?(inspected[:kind])
+            raise SecurityError, "cleanup inspection result unavailable"
+          end
+          kind = inspected.fetch(:kind).dup.freeze
+          unless original_owner || kind == "succeeded"
+            raise Ace::Runtime::RuntimeUnavailableError, "original cleanup lifetime exclusion unavailable"
+          end
+          result = result!(inspected.except(:kind), frame)
+          unless @observer.observe_self!(deadline: [deadline, Wire.deadline(5)].min) == original
+            raise SecurityError, "cleanup readback owner changed before inspection result"
+          end
+          success = kind == "succeeded"
+          Wire.write(socket, {"schema" => Client::SCHEMA, "kind" => success ? "completed-result" : "inspection",
+            "request_id" => frame.fetch("request_id"), "input_digest" => frame.fetch("input_digest"),
+            (success ? "receipt_ref" : "inspection_ref") => result.fetch(:receipt_ref)}, deadline: deadline, limit: Client::LIMIT)
+          descriptor = @codec.descriptor([result.fetch(:bytes)], purpose: :artifacts)
+          @codec.send(socket, parts: [result.fetch(:bytes)], descriptor: descriptor, purpose: :artifacts, deadline: deadline)
+        end
+
+        def hold_parent!(parent)
+          entries = []
+          paths = []
+          cursor = parent
+          loop do
+            paths << cursor
+            break if cursor == "/"
+            cursor = File.dirname(cursor)
+          end
+          paths.reverse_each do |path|
+            handle = File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+            handle.close_on_exec = true
+            entries << {path: path, handle: handle, identity: file_identity(handle.stat)}
+            @protection.verify!(path, handle, directory: true)
+            raise SecurityError, "cleanup parent changed while pinned" unless file_identity(File.lstat(path)) == entries.last.fetch(:identity)
+          end
+          complete = true
+          entries
+        ensure
+          entries&.each { |entry| entry.fetch(:handle).close } unless complete
+        end
+
+        def verify_parents!(entries)
+          entries.each do |entry|
+            unless file_identity(entry.fetch(:handle).stat) == entry.fetch(:identity) &&
+                file_identity(File.lstat(entry.fetch(:path))) == entry.fetch(:identity)
+              raise SecurityError, "cleanup protected ancestry changed"
+            end
+          end
+        end
+
+        def file_identity(stat) = [stat.dev, stat.ino, stat.uid, stat.gid, stat.mode]
+
+        def result!(result, frame)
+          unless result.is_a?(Hash) && result.keys.sort == %i[bytes receipt_ref] && result.fetch(:bytes).is_a?(String)
+            raise SecurityError, "cleanup fixed result unavailable"
+          end
+          ref = result.fetch(:receipt_ref)
+          Atoms::ProtectedWorkspacePruneInput.reference!(ref)
+          bytes = result.fetch(:bytes)
+          unless bytes.bytesize == ref.fetch("bytes") && Digest::SHA256.hexdigest(bytes) == ref.fetch("sha256")
+            raise SecurityError, "cleanup fixed result bytes differ"
+          end
+          result = {receipt_ref: JSON.parse(JSON.generate(ref)), bytes: bytes.dup}
+          Atoms::ProtectedWorkspacePruneInput.freeze_value(result)
+        end
+
+        def eof!(socket, deadline)
+          guarded = Wire::Ingress.new(socket)
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise Ace::Runtime::RuntimeUnavailableError, "cleanup request deadline expired" unless remaining.positive? && IO.select([socket], nil, nil, remaining)
+            value = guarded.read_nonblock(1, exception: false)
+            next if value == :wait_readable
+            raise SecurityError, "cleanup request contains trailing bytes" unless value.nil?
+            return
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/organisms/protected_service_client.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "protected_service_listener"
+
+module Ace
+  module Lab
+    module Organisms
+      # Worker-side short claim exchange. No local journal/executor fallback;
+      # outcome/recovery remains the existing protected authority service API.
+      class ProtectedServiceClient
+        def initialize(mapping_id:, service_id:, deployment: Ace::Assign::Authority::Deployment.load,
+          kernel: Ace::Runtime::Molecules::ProtectedLinux.new, wire: Ace::Runtime::Molecules::ProtectedSocket)
+          @deployment, @kernel, @wire, @mapping_id = deployment, kernel, wire, mapping_id
+          @map = deployment.mapping(mapping_id)
+          project = deployment.project(@map.fetch("project_id"))
+          @selection = project.fetch("service_receivers").fetch(service_id)
+          @credentials = project.fetch("peer_credentials").fetch(@selection.fetch("executor_uid").to_s)
+          @scratch = project.fetch("peer_credentials").fetch(@map.fetch("worker_uid").to_s).fetch("scratch_root")
+        end
+
+        def preview_workspace_prune(intent:)
+          intent = Atoms::ProtectedWorkspacePrunePreview.intent!(JSON.parse(JSON.generate(intent)))
+          bytes = JSON.generate(intent)
+          deadline = @wire.deadline(5)
+          @deployment.verify!(@mapping_id, kernel: @kernel)
+          caller = @kernel.capture(Process.pid)
+          unless caller.values_at("uid", "gid", "groups") == @map.values_at("worker_uid", "worker_gid", "worker_groups")
+            raise SecurityError, "preview caller differs"
+          end
+          codec = Ace::Assign::Authority::TransferCodec.new(root: @scratch)
+          descriptor = codec.descriptor([bytes], purpose: :service_input)
+          path = @selection.fetch("socket_path")
+          before = @wire.socket_identity(path)
+          raise SecurityError, "preview receiver owner differs" unless before.last == @selection.fetch("executor_uid")
+          @wire.connect(path, deadline: deadline) do |socket|
+            peer = @kernel.peer(socket)
+            unless peer.values_at("uid", "gid", "groups") == [@selection.fetch("executor_uid"), @credentials.fetch("gid"), @credentials.fetch("groups")] &&
+                @wire.socket_identity(path) == before
+              raise SecurityError, "preview receiver peer changed"
+            end
+            @wire.write(socket, {"version" => 1, "kind" => "preview_workspace_prune", "transfer" => descriptor},
+              deadline: deadline, limit: ProtectedServiceListener::LIMIT)
+            codec.send(socket, parts: [bytes], descriptor: descriptor, purpose: :service_input, deadline: deadline)
+            socket.shutdown(Socket::SHUT_WR)
+            guarded = Ace::Runtime::Molecules::ProtectedSocket::Ingress.new(socket)
+            result = @wire.read(guarded, deadline: deadline, limit: ProtectedServiceListener::LIMIT)
+            eof!(guarded, deadline)
+            raise SecurityError, "preview result unavailable" unless result.is_a?(Hash) && result.key?("maintenance_context")
+            Atoms::ProtectedWorkspacePrunePreview.context!(result.fetch("maintenance_context"))
+            Atoms::ProtectedWorkspacePrunePreview.result!(result, intent: intent, context: result.fetch("maintenance_context"))
+          end
+        end
+
+        def submit(submission:, input_bytes:, mutation_id:)
+          unless submission.is_a?(Hash) && submission.keys.sort == ProtectedServiceReceiver::SUBMISSION.sort &&
+              input_bytes.is_a?(String) && mutation_id.is_a?(String) && mutation_id.match?(Ace::Assign::Molecules::JournalMutation::ID)
+            raise ArgumentError, "receiver submission is invalid"
+          end
+          submission = JSON.parse(JSON.generate(submission))
+          bytes = input_bytes.dup.freeze
+          mutation_id = mutation_id.dup.freeze
+          deadline = @wire.deadline(5)
+          @deployment.verify!(@mapping_id, kernel: @kernel)
+          caller = @kernel.capture(Process.pid)
+          unless caller.values_at("uid", "gid", "groups") == @map.values_at("worker_uid", "worker_gid", "worker_groups")
+            raise SecurityError, "receiver caller differs"
+          end
+          codec = Ace::Assign::Authority::TransferCodec.new(root: @scratch)
+          descriptor = codec.descriptor([bytes], purpose: :service_input)
+          path = @selection.fetch("socket_path")
+          before = @wire.socket_identity(path)
+          raise SecurityError, "receiver endpoint owner differs" unless before.last == @selection.fetch("executor_uid")
+          @wire.connect(path, deadline: deadline) do |socket|
+            peer = @kernel.peer(socket)
+            unless peer.values_at("uid", "gid", "groups") == [@selection.fetch("executor_uid"), @credentials.fetch("gid"), @credentials.fetch("groups")] &&
+                @wire.socket_identity(path) == before
+              raise SecurityError, "receiver endpoint peer changed"
+            end
+            @wire.write(socket, {"version" => 1, "submission" => submission,
+              "mutation_id" => mutation_id, "transfer" => descriptor}, deadline: deadline, limit: ProtectedServiceListener::LIMIT)
+            codec.send(socket, parts: [bytes], descriptor: descriptor, purpose: :service_input, deadline: deadline)
+            socket.shutdown(Socket::SHUT_WR)
+            guarded = Ace::Runtime::Molecules::ProtectedSocket::Ingress.new(socket)
+            reply = @wire.read(guarded, deadline: deadline, limit: ProtectedServiceListener::LIMIT)
+            eof!(guarded, deadline)
+            validate_reply!(reply, submission.fetch("request_id"))
+            reply
+          end
+        rescue Ace::Runtime::RuntimeUnavailableError, IOError, SystemCallError, Timeout::Error
+          {"version" => 1, "type" => "service_claim_unconfirmed", "required_action" => "inspect_canonical_service_status"}
+        end
+
+        private
+
+        def eof!(socket, deadline)
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            unless remaining.positive? && IO.select([socket], nil, nil, remaining)
+              raise Ace::Runtime::RuntimeUnavailableError, "receiver reply EOF deadline expired"
+            end
+            byte = socket.read_nonblock(1, exception: false)
+            next if byte == :wait_readable
+            raise SecurityError, "receiver reply has trailing bytes" unless byte.nil?
+            return
+          end
+        end
+
+        def validate_reply!(reply, request_id)
+          unless reply.is_a?(Hash) && reply["version"].is_a?(Integer) && reply["version"] == 1
+            raise SecurityError, "receiver claim reply is invalid"
+          end
+          if reply["type"] == "service_claim_refused"
+            raise SecurityError, "receiver claim refusal is invalid" unless reply.keys.sort == %w[code type version] && %w[busy unavailable].include?(reply["code"])
+            return
+          end
+          data = reply["data"]
+          unless reply.keys.sort == %w[data type version] && reply["type"] == "service_claim_accepted" &&
+              data.is_a?(Hash) && (data.keys - %w[request_id generation journal_commit state claim replayed]).empty? &&
+              data["request_id"] == request_id && data["generation"].is_a?(Integer) && data["generation"].positive? &&
+              data["journal_commit"].is_a?(String) && data["journal_commit"].match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/) &&
+              %w[uncertain succeeded failed failed-settled].include?(data["state"]) && [true, false].include?(data["replayed"]) &&
+              (!data.key?("claim") || %w[created retained].include?(data["claim"]))
+            raise SecurityError, "receiver canonical claim identity differs"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/organisms/protected_service_listener.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "protected_service_worker"
+
+module Ace
+  module Lab
+    module Organisms
+      # Fixed receiver ingress. The short connection observes canonical claim
+      # acceptance; it does not own or cancel the admitted execution lifetime.
+      class ProtectedServiceListener
+        LIMIT = 16_384
+        REQUEST_KEYS = %w[mutation_id submission transfer version].freeze
+
+        def initialize(mapping_id:, service_id:, deployment: Ace::Assign::Authority::Deployment.load,
+          kernel: Ace::Runtime::Molecules::ProtectedLinux.new, receiver: nil,
+          wire: Ace::Runtime::Molecules::ProtectedSocket)
+          @deployment, @kernel, @wire = deployment, kernel, wire
+          @map = deployment.mapping(mapping_id)
+          project = deployment.project(@map.fetch("project_id"))
+          @selection = project.fetch("service_receivers").fetch(service_id)
+          @credentials = project.fetch("peer_credentials").fetch(@selection.fetch("executor_uid").to_s)
+          @path = @selection.fetch("socket_path")
+          @receiver = receiver || ProtectedServiceReceiver.new(
+            mapping_id: mapping_id, service_id: service_id, deployment: deployment, kernel: kernel)
+          @worker = ProtectedServiceWorker.new(receiver: @receiver)
+          @stopping = false
+        end
+
+        def serve
+          own_principal!
+          parent = File.dirname(@path)
+          @wire.root_path!(parent, directory: true, owner: @selection.fetch("executor_uid"))
+          # The installed receiver must actually be able to publish a socket
+          # accessible to its mapped worker. No ambient ACL/root fixup exists.
+          unless @credentials.fetch("gid") == @map.fetch("worker_gid") || @credentials.fetch("groups").include?(@map.fetch("worker_gid"))
+            raise SecurityError, "receiver socket group is unavailable"
+          end
+          @lock = File.open("#{@path}.lock", File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+          stat = @lock.stat
+          unless stat.file? && stat.uid == Process.uid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise SecurityError, "receiver listener lock differs"
+          end
+          unless @lock.flock(File::LOCK_EX | File::LOCK_NB)
+            raise Ace::Assign::AttemptErrors::Conflict, "receiver listener already active"
+          end
+          remove_stale_endpoint!
+          @listener = UNIXServer.new(@path)
+          File.chown(nil, @map.fetch("worker_gid"), @path)
+          File.chmod(0o660, @path)
+          @identity = @wire.socket_identity(@path)
+          until @stopping
+            begin
+              socket = @listener.accept
+              receive(socket)
+            ensure
+              socket&.close
+              socket = nil
+            end
+          end
+        rescue IOError, Errno::EBADF
+          raise unless @stopping
+        ensure
+          # Never release listener exclusion while an admitted worker exists.
+          # Actual operation transport supplies its separate bounded lifetime.
+          @worker.close(timeout: 1) until @worker.close(timeout: 0)
+          @listener&.close
+          remove_owned_endpoint!
+          @lock&.close
+        end
+
+        def stop
+          @stopping = true
+          @worker.close(timeout: 0)
+          @listener&.close
+        end
+
+        private
+
+        def receive(socket)
+          deadline = @wire.deadline(5)
+          peer = @kernel.peer(socket)
+          unless peer.values_at("uid", "gid", "groups") == @map.values_at("worker_uid", "worker_gid", "worker_groups")
+            raise SecurityError, "receiver worker peer differs"
+          end
+          guarded = Ace::Runtime::Molecules::ProtectedSocket::Ingress.new(socket)
+          request = @wire.read(guarded, deadline: deadline, limit: LIMIT)
+          if request.is_a?(Hash) && request["kind"] == "preview_workspace_prune"
+            unless request.keys.sort == %w[kind transfer version] && request["version"].is_a?(Integer) && request["version"] == 1
+              raise ArgumentError, "receiver preview header differs"
+            end
+            codec = Ace::Assign::Authority::TransferCodec.new(root: @selection.fetch("staging_root"))
+            bytes = codec.receive(guarded, descriptor: request.fetch("transfer"), purpose: :service_input, deadline: deadline) do |input|
+              raise ArgumentError, "preview requires one intent part" unless input.count == 1
+              input.bytes
+            end
+            intent = JSON.parse(bytes, create_additions: false, max_nesting: 16, allow_nan: false,
+              allow_comments: false, allow_duplicate_key: false)
+            intent = Atoms::ProtectedWorkspacePrunePreview.intent!(intent)
+            result = @receiver.preview_workspace_prune(intent: intent, peer: peer, deadline: deadline)
+            @wire.write(socket, result, deadline: deadline, limit: LIMIT)
+            return
+          end
+          strict_request!(request)
+          codec = Ace::Assign::Authority::TransferCodec.new(root: @selection.fetch("staging_root"))
+          bytes = codec.receive(guarded, descriptor: request.fetch("transfer"), purpose: :service_input, deadline: deadline) { |input| input.bytes }
+          completed = Queue.new
+          @worker.start(submission: request.fetch("submission"), peer: peer,
+            input_bytes: bytes, mutation_id: request.fetch("mutation_id"), deadline: deadline,
+            on_claim: lambda do |identity|
+              begin
+                @wire.write(socket, {"version" => 1, "type" => "service_claim_accepted", "data" => identity},
+                  deadline: deadline, limit: LIMIT)
+              rescue Ace::Runtime::RuntimeUnavailableError, IOError, SystemCallError
+                # Only bounded transport failure is swallowed. Original work
+                # continues and its accepted identity is observed via status.
+                nil
+              ensure
+                completed << true
+              end
+            end)
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          completed.pop(timeout: remaining) if remaining.positive?
+        rescue Ace::Assign::AttemptErrors::Conflict
+          refuse(socket, "busy", deadline)
+        rescue SecurityError, ArgumentError, KeyError, TypeError, Ace::Assign::Error,
+          Ace::Runtime::RuntimeUnavailableError, IOError, SystemCallError, Timeout::Error
+          refuse(socket, "unavailable", deadline)
+        end
+
+        def strict_request!(request)
+          unless request.is_a?(Hash) && request.keys.sort == REQUEST_KEYS &&
+              request["version"].is_a?(Integer) && request["version"] == 1 &&
+              request["transfer"].is_a?(Hash) && request["transfer"]["version"].is_a?(Integer) && request["transfer"]["version"] == 1 &&
+              request["mutation_id"].is_a?(String) && request["mutation_id"].match?(Ace::Assign::Molecules::JournalMutation::ID) &&
+              request["submission"].is_a?(Hash) && request["submission"].keys.sort == ProtectedServiceReceiver::SUBMISSION.sort
+            raise ArgumentError, "receiver request is invalid"
+          end
+          walk = [[request, 0]]
+          until walk.empty?
+            value, depth = walk.pop
+            raise ArgumentError, "receiver request depth exceeds bound" if depth > 16
+            children = value.is_a?(Hash) ? value.values : (value.is_a?(Array) ? value : [])
+            children.each { |child| walk << [child, depth + 1] }
+          end
+        end
+
+        def refuse(socket, code, deadline)
+          @wire.write(socket, {"version" => 1, "type" => "service_claim_refused", "code" => code}, deadline: deadline, limit: LIMIT)
+        rescue Ace::Runtime::RuntimeUnavailableError, IOError, SystemCallError
+          nil
+        end
+
+        def own_principal!
+          me = @kernel.capture(Process.pid)
+          unless me.values_at("uid", "gid", "groups") == [@selection.fetch("executor_uid"), @credentials.fetch("gid"), @credentials.fetch("groups")]
+            raise SecurityError, "receiver listener principal differs"
+          end
+          @kernel.live!(me)
+        end
+
+        def remove_stale_endpoint!
+          stat = File.lstat(@path)
+          unless stat.socket? && stat.uid == Process.uid
+            raise SecurityError, "receiver endpoint differs"
+          end
+          File.unlink(@path)
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def remove_owned_endpoint!
+          File.unlink(@path) if @identity && @wire.socket_identity(@path) == @identity
+        rescue Errno::ENOENT
+          nil
+        end
+
+      end
+    end
+  end
+end