ace-lab 0.7.0 → 0.9.0

data/lib/ace/lab/molecules/ordinary_listener.rb

@@ -12,7 +12,7 @@ module Ace
       # entrypoint). Binds the configured unix socket and answers the exact
       # framed protocol the OrdinarySocket client speaks: one bounded JSON
       # document each way behind the shared handshake line. Authentication is
-      # MUTUAL through SO_PEERCRED: every connection's peer UID must equal
+      # MUTUAL through OS peer credentials: every connection's peer UID must equal
       # the configured producer principal UID, and the listener itself runs
       # as the configured receiver UID — the identity the client verifies on
       # its side. Every identity, framing, deadline or parse failure is
@@ -24,11 +24,15 @@ module Ace
         LIMIT = OrdinarySocket::LIMIT
         DEADLINE_SECONDS = 30
 
-        def initialize(socket_path:, peer_uid:, handler:, lock_path: nil, logger: nil)
+        def initialize(socket_path:, peer_uid:, handler:, socket_gid: nil, lock_path: nil, logger: nil)
           unless socket_path.is_a?(String) && socket_path.start_with?("/") &&
               peer_uid.is_a?(Integer) && peer_uid >= 0 && handler.respond_to?(:call)
             raise ArgumentError, "ordinary listener needs an absolute socket path, a peer uid and a handler"
           end
+          unless socket_gid.nil? || (socket_gid.is_a?(Integer) && socket_gid >= 0)
+            raise ArgumentError, "ordinary listener socket_gid must be a non-negative integer"
+          end
+          @socket_gid = socket_gid
           @socket_path = socket_path
           @peer_uid = peer_uid
           @handler = handler
@@ -40,12 +44,15 @@ module Ace
         # Serve until #stop. Excludes a second listener through one owned
         # lock file, removes only its own stale endpoint, and always removes
         # the endpoint it created.
-        def serve
+        def serve(on_ready: nil)
           acquire_lock!
           remove_stale_endpoint!
           @listener = UNIXServer.new(@socket_path)
-          File.chmod(0o600, @socket_path)
           @endpoint_identity = File.stat(@socket_path)
+          File.chown(nil, @socket_gid, @socket_path) if @socket_gid
+          File.chmod(@socket_gid ? 0o660 : 0o600, @socket_path)
+          on_ready.call if on_ready
+          @handler.recover_pending! if @handler.respond_to?(:recover_pending!)
           until @stopping
             socket = @listener.accept
             serve_connection(socket)
@@ -59,6 +66,11 @@ module Ace
           @lock&.close
         end
 
+        # The existing listener participates in the Assign owner's lifetime.
+        def run(on_ready:)
+          serve(on_ready: on_ready)
+        end
+
         def stop
           @stopping = true
           @listener&.close
@@ -75,26 +87,27 @@ module Ace
             verify_peer!(socket)
             submission = read_request!(socket, deadline)
             response = @handler.call(submission)
-            write_response!(socket, response, deadline)
+            write_response_safely(socket, response, deadline)
             if response.is_a?(Hash) && response["status"] == "ok" && @handler.respond_to?(:execute)
               begin
-                # The durable acknowledgment is already on the wire; the
+                # Admission is durable even if the acknowledgment was lost; the
                 # execution lifetime belongs to the canonical record, not
                 # the short connection. A lost lifecycle stays pending or
                 # uncertain and reconciles by the original reference.
                 @handler.execute(response.dig("data", "request_id"))
-              rescue StandardError
-                nil
+              rescue StandardError => error
+                log_failure("effect", error)
               end
             end
           rescue OrdinaryRefused => e
-            write_response!(socket, e.envelope, deadline)
-          rescue OrdinaryListenerError
+            write_response_safely(socket, e.envelope, deadline)
+          rescue OrdinaryListenerError, IOError, SystemCallError => error
             # Fail closed without a fabricated envelope; the client classifies
             # a lost/unreadable response as ordinary_merge_unavailable.
-            nil
-          rescue StandardError
-            write_response!(socket, refusal_envelope("ordinary_merge_unavailable",
+            log_failure("connection", error)
+          rescue StandardError => error
+            log_failure("request", error)
+            write_response_safely(socket, refusal_envelope("ordinary_merge_unavailable",
               "receiver failed to handle the request"), deadline)
           ensure
             begin
@@ -119,16 +132,27 @@ module Ace
 
         private
 
-        # Mutual half of SO_PEERCRED: the connecting process must run as the
+        def write_response_safely(socket, response, deadline)
+          write_response!(socket, response, deadline)
+        rescue OrdinaryListenerError, IOError, SystemCallError => error
+          log_failure("response", error)
+        end
+
+        def log_failure(phase, error)
+          # Arbitrary exception messages may contain provider credentials or
+          # request bodies. Journal references remain the source of effect state.
+          @logger&.call("ordinary receiver #{phase} failed (#{error.class.name})")
+        end
+
+        # Mutual half of OS peer authentication: the connecting process must run as the
         # configured producer principal UID. Anything else is refused before
         # one byte of request is read.
         def verify_peer!(socket)
-          credentials = socket.getsockopt(:SOCKET, :PEERCRED)
-          _peer_pid, peer_uid, = credentials.unpack("L3")
+          peer_uid, = socket.getpeereid
           return if peer_uid == @peer_uid
           raise OrdinaryRefused, refusal_envelope("ordinary_merge_unauthenticated",
             "connecting principal is not the configured ordinary overseer")
-        rescue SystemCallError, IOError
+        rescue SystemCallError, IOError, SocketError, NotImplementedError
           raise OrdinaryListenerError, "peer credentials are unavailable"
         end
 

data/lib/ace/lab/molecules/ordinary_merge_read.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "ordinary_worktree_read"
+
+module Ace
+  module Lab
+    module Molecules
+      # Local checks are bounded read-only observations. Only the forge provider
+      # executes merge; moving a local ref can never prove a delivered merge.
+      class OrdinaryMergeRead
+        STRATEGY = "ff"
+
+        def initialize(repo_path:, base_ref:, root: repo_path, common_dir: File.join(repo_path, ".git"),
+          deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30)
+          unless repo_path.is_a?(String) && repo_path.start_with?("/") &&
+              base_ref.is_a?(String) && base_ref.start_with?("refs/")
+            raise ArgumentError, "ordinary merge read needs an absolute repository and full base ref"
+          end
+          @repo_path, @base_ref = repo_path, base_ref
+          @reader = OrdinaryWorktreeRead.new(root: root, common_dir: common_dir, deadline: deadline)
+        end
+
+        def base_head
+          @reader.ref_head(@repo_path, @base_ref)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        def candidate_commit?(head)
+          @reader.commit?(@repo_path, head)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        def fast_forwardable?(head)
+          @reader.ancestor?(@repo_path, base_head, head)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        class GitUnavailable < StandardError; end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_native_read.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "ace/runtime/molecules/protected_socket"
+require "ace/herdr/molecules/herdr_executor"
+require "ace/assign/authority/ordinary_peer"
+require_relative "ordinary_owner_config"
+
+module Ace
+  module Lab
+    module Molecules
+      # Read-only use of Herdr's existing native protocol. Root selection pins
+      # the endpoint inode and live server; no ambient CLI environment chooses
+      # the daemon, and no protected runtime guarantees are borrowed here.
+      class OrdinaryNativeRead
+        def initialize(config:, deadline:, peer: Ace::Assign::Authority::OrdinaryPeer.new)
+          raise ArgumentError, "native reader needs installed selection" unless config.is_a?(OrdinaryOwnerConfig)
+          @config, @deadline, @peer = config, deadline, peer
+          @native = config.native
+        end
+
+        def preflight!
+          result = request("ping", {})
+          unless result["type"] == "pong" && result.values_at("version", "protocol") == @native.values_at("version", "protocol")
+            unavailable!("native protocol differs from installed selection")
+          end
+          true
+        end
+
+        def pane_get(pane)
+          result = request("pane.get", {"pane_id" => pane})
+          unless result["type"] == "pane_info" && result["pane"].is_a?(Hash) && result["pane"]["pane_id"] == pane
+            unavailable!("native pane metadata differs from requested pane")
+          end
+          response(result)
+        end
+
+        def pane_process_info(pane)
+          @process_info = nil
+          result = request("pane.process_info", {"pane_id" => pane})
+          unless result["type"] == "pane_process_info" && result["process_info"].is_a?(Hash) && result["process_info"]["pane_id"] == pane
+            unavailable!("native process inventory differs from requested pane")
+          end
+          @process_info = result.fetch("process_info")
+          response(result)
+        end
+
+        # This per-PID native field comes from process_cwd, not the terminal's
+        # OSC/UI working directory. The caller separately verifies PID birth.
+        def process_cwd(pid)
+          processes = @process_info.is_a?(Hash) && @process_info["foreground_processes"]
+          unavailable!("native process inventory is unavailable") unless processes.is_a?(Array)
+          matches = processes.select { |entry| entry.is_a?(Hash) && entry["pid"] == pid }
+          path = matches.one? && matches.first["cwd"]
+          unless path.is_a?(String) && path.bytesize.between?(1, 4096) && !path.include?("\0") &&
+              path.start_with?("/") && File.expand_path(path) == path
+            unavailable!("exact native process working directory is unavailable")
+          end
+          path
+        end
+
+        private
+
+        def request(method, params)
+          verify_endpoint!
+          wire.connect(@native.fetch("socket_path"), deadline: @deadline) do |socket|
+            unless @peer.capture(socket, deadline: @deadline) == @native.fetch("server_identity")
+              unavailable!("native peer differs from installed server")
+            end
+            verify_endpoint!
+            id = SecureRandom.hex(12)
+            wire.write(socket, {"id" => id, "method" => method, "params" => params}, deadline: @deadline, limit: 16_384)
+            value = wire.read(wire::Ingress.new(socket), deadline: @deadline, limit: 65_536)
+            unless value.is_a?(Hash) && value.keys.sort == %w[id result] && value["id"] == id && value["result"].is_a?(Hash)
+              unavailable!("native read response is invalid")
+            end
+            verify_endpoint!
+            @peer.live!(@native.fetch("server_identity"), deadline: @deadline)
+            value.fetch("result")
+          end
+        rescue SystemCallError, IOError, KeyError, Ace::Assign::AttemptErrors::UnauthorizedIdentity
+          unavailable!("native read is unavailable")
+        end
+
+        def verify_endpoint!
+          @config.verify_selection!
+          path = @native.fetch("socket_path")
+          wire.root_path!(File.dirname(path), directory: true)
+          unless wire.socket_identity(path) == @native.fetch("socket_identity") && (File.lstat(path).mode & 0o007).zero?
+            unavailable!("native endpoint generation or access differs")
+          end
+        end
+
+        def response(result)
+          Ace::Herdr::Molecules::ExecutionResult.new(stdout: JSON.generate({"result" => result}), stderr: "", success: true, exit_code: 0)
+        end
+
+        def wire = Ace::Runtime::Molecules::ProtectedSocket
+
+        def unavailable!(reason)
+          raise Ace::Runtime::RuntimeUnavailableError, reason
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_owner_admission.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "ace/assign/authority/ordinary_peer"
+require "ace/assign/molecules/execution_identity_resolver"
+require "ace/herdr"
+require_relative "ordinary_owner_config"
+require_relative "ordinary_native_read"
+require_relative "ordinary_worktree_read"
+
+module Ace
+  module Lab
+    module Molecules
+      # The source-selected ordinary peer policy. Native selectors are hints;
+      # only actual ancestry in the installed project's Herdr grants attribution.
+      class OrdinaryOwnerAdmission
+        def initialize(config:, peer: Ace::Assign::Authority::OrdinaryPeer.new, runtime: nil)
+          raise ArgumentError, "ordinary owner requires validated installed selection" unless config.is_a?(OrdinaryOwnerConfig)
+          @config, @peer = config, peer
+          @runtime = runtime
+        end
+
+        def service = @config.service
+        def verify_listener!
+          @config.verify_listener!
+          OrdinaryNativeRead.new(config: @config, deadline: default_deadline, peer: @peer).preflight!
+        end
+        def peer(socket, deadline:) = @peer.capture(socket, deadline: deadline)
+
+        def authorize!(request:, peer:, deadline: default_deadline)
+          @peer.live!(peer, deadline: deadline)
+          unless request.fetch("project_id") == @config.project
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary request belongs to another project"
+          end
+          @config.participant!(peer)
+          pane = request.fetch("params", {})["pane"]
+          # Reads need project visibility only. Every mutating lifecycle route
+          # validates a pane; supervisor authority additionally requires actual
+          # caller ancestry in one of the root-installed native placements.
+          return :worker unless pane
+          identity!(peer: peer, pane: pane, deadline: deadline).role == "coordinator" ? :supervisor : :worker
+        end
+
+        def identity!(peer:, pane:, deadline: default_deadline)
+          observe_identity(peer: peer, pane: pane, deadline: deadline, with_cwd: false).first
+        end
+
+        def supervisor_ended!(binding:, deadline: default_deadline)
+          @config.verify_selection!
+          process = binding.fetch("process_identity")
+          @config.selected_principal!(process.fetch("uid"))
+          observation = Ace::Herdr::Molecules::BoundedObservation.new(deadline: deadline, binary: @config.runtime_binary)
+          result = Ace::Runtime::Molecules::ProcessIdentity.new(executor: observation).generation_status(process)
+          unless result.fetch("liveness") == "ended"
+            raise Ace::Assign::AttemptErrors::EvidenceUnavailable, "original supervisor process generation is live or unknown"
+          end
+          @config.verify_selection!
+          result
+        end
+
+        # The caller's claimed head is only a comparison. The accepted start
+        # uses the observed worker's checkout and process, never daemon cwd.
+        def execution!(peer:, pane:, head:, deadline: default_deadline)
+          unless head.is_a?(String) && head.match?(/\A[0-9a-f]{40}\z/)
+            raise ArgumentError, "ordinary start HEAD is invalid"
+          end
+          identity, cwd = observe_identity(peer: peer, pane: pane, deadline: deadline, with_cwd: true)
+          checkout = OrdinaryWorktreeRead.new(root: @config.worktrees.fetch("root"),
+            common_dir: @config.worktrees.fetch("common_dir"), deadline: deadline).observe(cwd)
+          after, after_cwd = observe_identity(peer: peer, pane: pane, deadline: deadline, with_cwd: true)
+          unless after == identity && after_cwd == cwd && checkout.fetch("head") == head
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary worker process, working directory or HEAD changed"
+          end
+          {identity: identity, checkout: checkout}
+        end
+
+        # Read the original canonical native owner for a trusted consumer.
+        # The binding must come from accepted history, never requester fields.
+        # This observes ownership; it does not grant the target's privileges to
+        # the caller or manufacture a kernel-authenticated connection identity.
+        def recorded_binding!(binding:, caller_pid: nil, deadline: default_deadline)
+          observe_recorded_binding(binding, caller_pid, deadline).first
+        end
+
+        def recorded_execution!(binding:, head:, deadline: default_deadline)
+          before, cwd = observe_recorded_binding(binding, nil, deadline)
+          checkout = OrdinaryWorktreeRead.new(root: @config.worktrees.fetch("root"),
+            common_dir: @config.worktrees.fetch("common_dir"), deadline: deadline).observe(cwd)
+          after, after_cwd = observe_recorded_binding(binding, nil, deadline)
+          unless before == after && cwd == after_cwd && checkout.fetch("head") == head
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary recorded worker or HEAD changed"
+          end
+          {runtime_binding: after, checkout: checkout}
+        end
+
+        private
+
+        def observe_recorded_binding(binding, caller_pid, deadline)
+          @config.verify_selection!
+          uid = binding.fetch("process_identity").fetch("uid")
+          participant = @config.selected_principal!(uid)
+          unless participant && binding["runtime"] == participant.fetch("runtime") && binding["session"] == participant.fetch("workspace")
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary recorded participant is no longer selected"
+          end
+          native, runtime = native_runtime(deadline)
+          actual = runtime.process_binding(pane: binding.fetch("pane"), caller_pid: caller_pid || binding.fetch("process_identity").fetch("pid"))
+          unless actual == binding
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary recorded native owner is unavailable or changed"
+          end
+          cwd = native.process_cwd(binding.fetch("process_identity").fetch("pid"))
+          @config.selected_principal!(uid)
+          [actual, cwd]
+        end
+
+        def native_runtime(deadline)
+          return [@runtime, @runtime] if @runtime
+          observation = Ace::Herdr::Molecules::BoundedObservation.new(deadline: deadline, binary: @config.runtime_binary)
+          native = OrdinaryNativeRead.new(config: @config, deadline: deadline, peer: @peer)
+          native.preflight!
+          [native, Ace::Herdr::Organisms::RuntimeAdapter.new(executor: native, env: {},
+            process_identity: Ace::Runtime::Molecules::ProcessIdentity.new(executor: observation))]
+        end
+
+        def observe_identity(peer:, pane:, deadline:, with_cwd:)
+          @peer.live!(peer, deadline: deadline)
+          participant = @config.participant!(peer)
+          unless pane.is_a?(String) && pane.bytesize.between?(1, 128) && !pane.include?("\0")
+            raise ArgumentError, "ordinary native pane selector is invalid"
+          end
+          native, runtime = native_runtime(deadline)
+          binding = runtime.process_binding(pane: pane, caller_pid: peer.fetch("pid"))
+          unless binding && binding["runtime"] == participant.fetch("runtime") &&
+              binding["session"] == participant.fetch("workspace") && binding["pane"] == pane &&
+              binding.dig("process_identity", "uid") == peer.fetch("uid")
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary native owner is unavailable or differs"
+          end
+          @peer.live!(peer, deadline: deadline)
+          @config.participant!(peer)
+          # Ordinary native agents may share an OS account. Preserve that actor
+          # for HITL attribution; privilege follows observed native placement,
+          # not a claimed role or an invented per-agent account alias.
+          role = participant.fetch("supervisor_panes").include?(binding.fetch("pane")) ? "coordinator" : "worker"
+          identity = Ace::Assign::Molecules::ExecutionIdentityResolver::Identity.new(
+            actor: participant.fetch("actor"), role: role, runtime: participant.fetch("runtime"),
+            adapter: "ordinary", process_pid: binding.fetch("process_identity").fetch("pid"), runtime_binding: binding)
+          [identity, with_cwd ? native.process_cwd(identity.process_pid) : nil]
+        end
+
+        def default_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_owner_config.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+require "digest"
+require "etc"
+require "ace/assign/authority/private_directory"
+require "ace/assign/authority/protected_assignment_context"
+require "ace/assign/molecules/installed_journal_read"
+require "ace/runtime/molecules/protected_artifact_set"
+require "ace/hitl/lifecycle/store"
+require_relative "../errors"
+
+module Ace
+  module Lab
+    module Molecules
+      # Placement and principals only. Source selects lifecycle operations.
+      # Root installs this independently of requester worktrees/config cascades.
+      class OrdinaryOwnerConfig
+        PATH = "/etc/lab/ace-lab/assign-owners.yml"
+        ID = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/
+        PROJECT_KEYS = %w[service journal assignment_root lifecycle_root runtime_binary native worktrees participants hitl].freeze
+        SERVICE_KEYS = %w[uid gid socket_path state_root].freeze
+        JOURNAL_KEYS = %w[repository ref checkout_root].freeze
+        PARTICIPANT_KEYS = %w[gid actor runtime workspace supervisor_panes].freeze
+        PANE = /\A[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}\z/
+        NATIVE_KEYS = %w[socket_path socket_identity server_identity version protocol].freeze
+        HITL_KEYS = %w[root socket_path group grants_path].freeze
+        HITL_OPTIONAL_KEYS = %w[tls_authority].freeze
+
+        def self.load(project:, path: PATH)
+          reader = Ace::Runtime::Molecules::ProtectedArtifactSet.new(file_limit: 65_536, total_limit: 65_536)
+          bytes = reader.with do |held|
+            content, = held.read_path!(path)
+            held.verify_unchanged!
+            content
+          end
+          new(YAML.safe_load(bytes, aliases: false), project: project, source: path)
+        rescue Psych::Exception, Ace::Runtime::Error
+          raise InvalidConfigurationError, "ordinary assignment owner configuration is unavailable: #{path}"
+        end
+
+        attr_reader :project, :service, :journal, :assignment_root, :lifecycle_root,
+          :runtime_binary, :native, :worktrees, :participants, :hitl, :source
+
+        def initialize(document, project:, source:)
+          unless document.is_a?(Hash) && document.keys.sort == %w[projects version] && document["version"] == 1 &&
+              document["projects"].is_a?(Hash) && document["projects"].keys.all? { |id| id.is_a?(String) && ID.match?(id) } &&
+              project.is_a?(String) && ID.match?(project)
+            invalid!
+          end
+          selected = document.fetch("projects")[project]
+          validate_principal_separation!(document.fetch("projects"))
+          invalid! unless selected.is_a?(Hash) && selected.keys.sort == PROJECT_KEYS.sort
+          invalid! unless absolute?(source)
+          @project, @source = project.dup.freeze, source.dup.freeze
+          # Validate a detached immutable copy; callers cannot mutate trusted selection.
+          selected = JSON.parse(JSON.generate(selected))
+          @service, @journal, @participants = selected.values_at("service", "journal", "participants")
+          invalid! unless @service.is_a?(Hash) && @service.keys.sort == SERVICE_KEYS.sort &&
+            %w[uid gid].all? { |key| uid?(@service[key]) } &&
+            %w[socket_path state_root].all? { |key| absolute?(@service[key]) }
+          invalid! unless @journal.is_a?(Hash) && @journal.keys.sort == JOURNAL_KEYS.sort &&
+            %w[repository checkout_root].all? { |key| absolute?(@journal[key]) } &&
+            @journal["ref"].is_a?(String) && @journal["ref"].match?(%r{\Arefs/[a-zA-Z0-9_-]+(?:/[a-zA-Z0-9_-]+)+\z})
+          @assignment_root, @lifecycle_root, @runtime_binary = selected.values_at("assignment_root", "lifecycle_root", "runtime_binary")
+          invalid! unless [@assignment_root, @lifecycle_root, @runtime_binary].all? { |path| absolute?(path) }
+          @native = selected.fetch("native")
+          invalid! unless @native.is_a?(Hash) && @native.keys.sort == NATIVE_KEYS.sort && absolute?(@native["socket_path"]) &&
+            @native["protocol"] == 22 && @native["protocol"].is_a?(Integer) && @native["version"].is_a?(String) &&
+            @native["version"].match?(/\A\d+\.\d+\.\d+\z/)
+          server = @native["server_identity"]
+          invalid! unless server.is_a?(Hash) && server.keys.sort == %w[gid host pid started_at uid] &&
+            %w[pid uid gid].all? { |key| uid?(server[key]) } &&
+            %w[host started_at].all? { |key| server[key].is_a?(String) && server[key].bytesize.between?(1, 512) && !server[key].include?("\0") }
+          endpoint = @native["socket_identity"]
+          invalid! unless endpoint.is_a?(Array) && endpoint.size == 3 && endpoint.all? { |value| value.is_a?(Integer) && value >= 0 } && endpoint.last.zero?
+          @worktrees = selected.fetch("worktrees")
+          invalid! unless @worktrees.is_a?(Hash) && @worktrees.keys.sort == %w[common_dir root] && @worktrees.values.all? { |path| absolute?(path) }
+          @hitl = selected.fetch("hitl")
+          invalid! unless @hitl.is_a?(Hash) && (HITL_KEYS - @hitl.keys).empty? &&
+            (@hitl.keys - HITL_KEYS - HITL_OPTIONAL_KEYS).empty? &&
+            %w[root socket_path grants_path].all? { |key| absolute?(@hitl[key]) } &&
+            (!@hitl.key?("tls_authority") || absolute?(@hitl["tls_authority"])) &&
+            @hitl["group"].is_a?(String) && ID.match?(@hitl["group"]) &&
+            [@service.fetch("socket_path"), @native.fetch("socket_path"), @hitl.fetch("socket_path")].uniq.size == 3
+          private_paths = [@assignment_root, @lifecycle_root, @journal.fetch("checkout_root"), @hitl.fetch("root")]
+          invalid! unless private_paths.all? { |path| path.start_with?(@service.fetch("state_root") + "/") } &&
+            private_paths.uniq.size == private_paths.size && private_paths.combination(2).none? { |a, b| a.start_with?(b + "/") || b.start_with?(a + "/") }
+          invalid! if @journal.fetch("repository").start_with?(@service.fetch("state_root") + "/") ||
+            @service.fetch("state_root").start_with?(@journal.fetch("repository") + "/") ||
+            @service.fetch("state_root") == @journal.fetch("repository")
+          invalid! unless @participants.is_a?(Hash) && !@participants.empty? && @participants.size <= 64
+          @participants.each do |uid, participant|
+            invalid! unless uid.is_a?(String) && uid.match?(/\A[1-9][0-9]{0,9}\z/) && uid?(uid.to_i) && uid.to_i != @service.fetch("uid") &&
+              participant.is_a?(Hash) && participant.keys.sort == PARTICIPANT_KEYS.sort && uid?(participant["gid"]) &&
+              participant["actor"].is_a?(String) && ID.match?(participant["actor"]) &&
+              participant["runtime"] == "herdr" && participant["workspace"].is_a?(String) && ID.match?(participant["workspace"]) &&
+              participant["supervisor_panes"].is_a?(Array) && participant["supervisor_panes"].size <= 16 &&
+              participant["supervisor_panes"].uniq == participant["supervisor_panes"] &&
+              participant["supervisor_panes"].all? { |pane| pane.is_a?(String) && PANE.match?(pane) }
+          end
+          invalid! unless @participants.values.map { |value| value.fetch("actor") }.uniq.size == @participants.size
+          @fingerprint = Digest::SHA256.hexdigest(Ace::Assign::Atoms::EvidenceDigest.canonical_json(selected))
+          freeze_value(selected)
+          freeze
+        end
+
+        def verify_selection!
+          current = self.class.load(project: @project, path: @source)
+          unless current.fingerprint == @fingerprint
+            raise InvalidConfigurationError, "ordinary assignment owner selection changed; restart with installed configuration"
+          end
+          true
+        end
+
+        def verify_listener!
+          verify_owner!
+          unless [Process.uid, Process.euid, Process.gid, Process.egid] ==
+              [@service.fetch("uid"), @service.fetch("uid"), @service.fetch("gid"), @service.fetch("gid")]
+            raise InvalidConfigurationError, "ordinary assignment owner process differs"
+          end
+          ([service.fetch("uid")] + participants.keys.map(&:to_i)).each { |uid| exclude_protected!(uid) }
+          [@service.fetch("state_root"), @assignment_root, @lifecycle_root, @journal.fetch("checkout_root")].each do |path|
+            Ace::Assign::Authority::PrivateDirectory.verify!(path)
+          end
+          verify_hitl_root!
+          wire = Ace::Runtime::Molecules::ProtectedSocket
+          wire.root_path!(@runtime_binary)
+          invalid! unless File.file?(@runtime_binary) && File.executable?(@runtime_binary)
+          invalid! unless File.lstat(@journal.fetch("repository")).uid == @service.fetch("uid")
+          reader = Ace::Assign::Molecules::InstalledJournalRead.new(repo_root: @journal.fetch("repository"),
+            ref: @journal.fetch("ref"), owner_uid: @service.fetch("uid"))
+          reader.with(deadline: wire.deadline(30)) { |_snapshot| true }
+          true
+        end
+
+        def verify_owner!
+          verify_selection!
+          exclude_protected!(@service.fetch("uid"))
+          true
+        end
+
+        def participant!(peer)
+          participant = selected_principal!(peer.fetch("uid"))
+          unless participant.fetch("gid") == peer.fetch("gid")
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary participant group differs"
+          end
+          participant
+        end
+
+        # Selection only: consumers of canonical native history have an
+        # observed process UID, not a new authenticated socket from that owner.
+        def selected_principal!(uid)
+          verify_owner!
+          exclude_protected!(uid)
+          participant = @participants[uid.to_s]
+          unless participant
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary participant is not installed for this project"
+          end
+          # HITL and the canonical coordinator use the authenticated passwd
+          # principal. An unrelated display label cannot replace that identity.
+          unless Etc.getpwuid(uid).name == participant.fetch("actor")
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary actor differs from installed OS principal"
+          end
+          participant
+        rescue ArgumentError
+          raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "ordinary OS principal is unavailable"
+        end
+
+        protected
+
+        attr_reader :fingerprint
+
+        private
+
+        # HITL maintains its own layout (root 0711, private request/secret
+        # directories). The already-verified private state_root encloses it.
+        # Requiring a 0700 HITL leaf would reject every normal service restart.
+        def verify_hitl_root!
+          root = @hitl.fetch("root")
+          Ace::Runtime::Molecules::ProtectedSocket.root_path!(root, directory: true, owner: @service.fetch("uid"))
+          unless (File.stat(root).mode & 0o7777) == Ace::Hitl::Lifecycle::Store::ROOT_MODE
+            raise InvalidConfigurationError, "ordinary HITL store root must use the maintained store mode"
+          end
+          true
+        end
+
+        def validate_principal_separation!(projects)
+          invalid! unless projects.size.between?(1, 64)
+          owners, callers = [], []
+          projects.each_value do |entry|
+            invalid! unless entry.is_a?(Hash) && entry["service"].is_a?(Hash) &&
+              uid?(entry["service"]["uid"]) && entry["participants"].is_a?(Hash)
+            owners << entry.fetch("service").fetch("uid")
+            entry.fetch("participants").each_key do |uid|
+              invalid! unless uid.is_a?(String) && uid.match?(/\A[1-9][0-9]{0,9}\z/) && uid?(uid.to_i)
+              callers << uid.to_i
+            end
+          end
+          invalid! unless (owners & callers).empty?
+        end
+
+        def exclude_protected!(uid)
+          context = Ace::Assign::Authority::ProtectedAssignmentContext.load(uid: uid)
+          if context.protected_participant?
+            raise Ace::Assign::AttemptErrors::UnauthorizedIdentity, "protected principal cannot use ordinary assignment authority"
+          end
+        end
+
+        def absolute?(value)
+          value.is_a?(String) && value.bytesize.between?(1, 4096) && !value.include?("\0") &&
+            value.start_with?("/") && File.expand_path(value) == value
+        end
+
+        def uid?(value) = value.is_a?(Integer) && value.between?(1, 2**31 - 1)
+
+        def freeze_value(value)
+          case value
+          when Hash then value.each { |key, item| key.freeze; freeze_value(item) }
+          when Array then value.each { |item| freeze_value(item) }
+          end
+          value.freeze
+        end
+
+        def invalid!
+          raise InvalidConfigurationError, "ordinary assignment owner configuration is invalid"
+        end
+      end
+    end
+  end
+end