ace-lab 0.8.0 → 0.13.0

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

@@ -1,232 +0,0 @@
-# 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

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

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-require_relative "../errors"
-require_relative "service_policy"
-require_relative "grant_resolver"
-
-module Ace
-  module Lab
-    module Molecules
-      # Project-scoped, explicitly filed receiver configuration (spec
-      # 8x3.t.xz9.4 execution clauses). The host owns the file, its
-      # placement, its credentials and its deployment; this loader only
-      # validates the exact closed shape and fails closed on anything else.
-      # It invents no credential and accepts no caller-selected endpoint:
-      # every value comes from one explicit deployment-owned YAML file.
-      class OrdinaryReceiverConfig
-        KEYS = %w[project receiver_id socket_path receiver_uid principal principal_uid
-          repo_path policy_path execution_identity].freeze
-        OPTIONAL_KEYS = %w[socket_gid forge_config_path].freeze
-        IDENTITY_KEYS = %w[checkout_id worktree_id branch].freeze
-        ID = ServicePolicy::ID
-
-        def self.load(path)
-          raise Ace::Lab::InvalidConfigurationError, "receiver config path is required" unless path.is_a?(String) && !path.empty?
-          bytes = GrantResolver.read_verified(path)
-          raise Ace::Lab::InvalidConfigurationError, "receiver configuration is missing" unless bytes
-          document = YAML.safe_load(bytes, permitted_classes: [Date], aliases: false)
-          new(document, source: path)
-        rescue Errno::ENOENT, Errno::EACCES, Psych::Exception
-          raise Ace::Lab::InvalidConfigurationError, "receiver configuration is unreadable: #{path}"
-        end
-
-        attr_reader :project, :receiver_id, :socket_path, :receiver_uid, :principal,
-          :principal_uid, :repo_path, :policy_path, :execution_identity, :source, :socket_gid, :forge_config_path
-
-        def initialize(document, source: nil)
-          unless document.is_a?(Hash) && (document.keys - KEYS - OPTIONAL_KEYS).empty? &&
-              (KEYS - document.keys).empty?
-            raise Ace::Lab::InvalidConfigurationError,
-              "receiver configuration requires #{KEYS.join(', ')}; optional: #{OPTIONAL_KEYS.join(', ')}"
-          end
-          @socket_gid = uid!(document.fetch("socket_gid"), "socket_gid") if document.key?("socket_gid")
-          @forge_config_path = absolute!(document.fetch("forge_config_path"), "forge_config_path") if
-            document.key?("forge_config_path")
-          @source = source
-          @project = string!(document.fetch("project"), "project")
-          @receiver_id = string!(document.fetch("receiver_id"), "receiver_id")
-          @principal = string!(document.fetch("principal"), "principal")
-          @socket_path = absolute!(document.fetch("socket_path"), "socket_path")
-          @repo_path = absolute!(document.fetch("repo_path"), "repo_path")
-          @policy_path = absolute!(document.fetch("policy_path"), "policy_path")
-          @receiver_uid = uid!(document.fetch("receiver_uid"), "receiver_uid")
-          raise Ace::Lab::InvalidConfigurationError, "ordinary receiver must have a non-root owner" if @receiver_uid.zero?
-          @principal_uid = uid!(document.fetch("principal_uid"), "principal_uid")
-          identity = document.fetch("execution_identity")
-          unless identity.is_a?(Hash) && (identity.keys - IDENTITY_KEYS).empty? &&
-              IDENTITY_KEYS.all? { |key| identity[key].is_a?(String) && !identity[key].empty? }
-            raise Ace::Lab::InvalidConfigurationError,
-              "receiver execution_identity is incomplete"
-          end
-          @execution_identity = IDENTITY_KEYS.to_h { |key| [key, identity.fetch(key)] }.freeze
-          unless @repo_path.start_with?("/") && File.directory?(@repo_path)
-            raise Ace::Lab::InvalidConfigurationError, "receiver repo_path is not a directory"
-          end
-          freeze
-        end
-
-        private
-
-        def string!(value, name)
-          unless value.is_a?(String) && !value.empty? && value.length <= 256 && value.match?(ID)
-            raise Ace::Lab::InvalidConfigurationError, "receiver #{name} is invalid"
-          end
-          value
-        end
-
-        def absolute!(value, name)
-          unless value.is_a?(String) && value.start_with?("/") && value.length <= 1024
-            raise Ace::Lab::InvalidConfigurationError, "receiver #{name} must be an absolute path"
-          end
-          value
-        end
-
-        def uid!(value, name)
-          unless value.is_a?(Integer) && value >= 0
-            raise Ace::Lab::InvalidConfigurationError, "receiver #{name} must be a non-negative integer"
-          end
-          value
-        end
-      end
-    end
-  end
-end

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

@@ -1,126 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "socket"
-
-module Ace
-  module Lab
-    module Molecules
-      # Admission transport between the ordinary fixed merge producer and the
-      # installed ordinary receiver: one bounded JSON document each way over
-      # a configured unix stream socket with a fixed deadline. Authentication
-      # is mutual through OS peer credentials — the producer verifies the receiver's
-      # configured UID and transmits the verified local caller identity, so
-      # no caller-selected credential, token or endpoint exists. This is not
-      # an HTTP transport; a lost or unauthenticated response is a
-      # caller-side blocker (ordinary_merge_unavailable), never a refusal.
-      class OrdinarySocket
-        LIMIT = 16_384
-        HANDSHAKE = "ace-lab/ordinary-merge/v1"
-
-        # @param socket_path [String] installed receiver endpoint (configuration)
-        # @param receiver_uid [Integer] the only UID the receiver may run as
-        # @param deadline [Time] absolute deadline for connect/write/read
-        def initialize(socket_path:, receiver_uid:, deadline: Time.now.utc + 30)
-          @socket_path = socket_path
-          @receiver_uid = receiver_uid
-          @deadline = deadline
-        end
-
-        # Submit one bounded request document; returns the parsed response
-        # document. Any framing, deadline or identity failure raises
-        # OrdinaryUnavailable so the producer can classify the blocker.
-        def submit(document)
-          payload = JSON.generate(document)
-          raise OrdinaryUnavailable, "request document exceeds the wire bound" if payload.bytesize > LIMIT
-          socket = nil
-          begin
-            socket = UNIXSocket.new(@socket_path)
-            verify_peer!(socket)
-            write_all!(socket, "#{HANDSHAKE} #{payload.bytesize}\n#{payload}")
-            response = read_response!(socket)
-          rescue OrdinaryUnavailable
-            raise
-          rescue SystemCallError, IOError, SocketError, NotImplementedError => e
-            raise OrdinaryUnavailable, "receiver transport failed: #{e.class}"
-          ensure
-            begin
-              socket&.close
-            rescue IOError
-              nil
-            end
-          end
-          response
-        end
-
-        class OrdinaryUnavailable < ::StandardError; end
-
-        private
-
-        def verify_peer!(socket)
-          peer_uid, = socket.getpeereid
-          return if peer_uid == @receiver_uid
-          raise OrdinaryUnavailable, "receiver endpoint identity is not the installed receiver"
-        end
-
-        def write_all!(socket, bytes)
-          written = 0
-          while written < bytes.bytesize
-            begin
-              raise OrdinaryUnavailable, "receiver write deadline expired" if expired?
-              written += socket.write_nonblock(bytes.byteslice(written..))
-            rescue IO::WaitWritable
-              socket.wait_writable(remaining!) or raise OrdinaryUnavailable, "receiver write deadline expired"
-            end
-          end
-        end
-
-        def read_response!(socket)
-          header = read_line!(socket)
-          match = /\A#{Regexp.escape(HANDSHAKE)} (\d{1,5})\n\z/o.match(header)
-          raise OrdinaryUnavailable, "receiver response header is invalid" unless match
-          length = Integer(match[1])
-          raise OrdinaryUnavailable, "receiver response exceeds the wire bound" if length > LIMIT
-          body = read_exact!(socket, length)
-          JSON.parse(body, allow_duplicate_key: false, create_additions: false, max_nesting: 16)
-        rescue JSON::ParserError
-          raise OrdinaryUnavailable, "receiver response is not valid JSON"
-        end
-
-        def read_line!(socket)
-          line = +""
-          until line.end_with?("\n")
-            raise OrdinaryUnavailable, "receiver response header is unbounded" if line.bytesize > 128
-            line << read_exact!(socket, 1)
-          end
-          line
-        end
-
-        def read_exact!(socket, length)
-          buffer = +""
-          while buffer.bytesize < length
-            begin
-              raise OrdinaryUnavailable, "receiver read deadline expired" if expired?
-              chunk = socket.read_nonblock(length - buffer.bytesize)
-              raise OrdinaryUnavailable, "receiver closed the connection" if chunk.nil?
-              buffer << chunk
-            rescue IO::WaitReadable
-              socket.wait_readable(remaining!) or raise OrdinaryUnavailable, "receiver read deadline expired"
-            end
-          end
-          buffer
-        end
-
-        def expired?
-          Time.now.utc >= @deadline
-        end
-
-        def remaining!
-          left = @deadline - Time.now.utc
-          raise OrdinaryUnavailable, "receiver deadline expired" if left <= 0
-          left
-        end
-      end
-    end
-  end
-end

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

@@ -1,216 +0,0 @@
-# frozen_string_literal: true
-
-require "ace/assign/molecules/installed_journal_read"
-
-module Ace
-  module Lab
-    module Molecules
-      # Observe a mutable ordinary worker checkout. The root-installed project
-      # selection supplies both boundaries; caller input never selects a Git
-      # repository. This is historical observation, not a checkout freeze.
-      class OrdinaryWorktreeRead
-        def initialize(root:, common_dir:, deadline:)
-          @root, @common, @deadline = root, common_dir, deadline
-          [root, common_dir].each { |path| absolute!(path) }
-        end
-
-        def observe(cwd)
-          absolute!(cwd)
-          remaining
-          unless within?(cwd, @root)
-            unavailable!("worker working directory is outside installed worktrees")
-          end
-          before = selection(cwd)
-          head = git(before, "rev-parse", "--verify", "HEAD^{commit}").strip
-          unavailable!("worker HEAD is unavailable") unless head.match?(/\A[0-9a-f]{40}\z/)
-          after = selection(cwd)
-          unless before == after && git(after, "rev-parse", "--verify", "HEAD^{commit}").strip == head
-            unavailable!("worker checkout changed during observation")
-          end
-          {"cwd" => cwd, "worktree" => before.fetch("worktree"), "git_dir" => before.fetch("git_dir"),
-            "common_dir" => @common, "head" => head}
-        rescue SystemCallError, IOError, Timeout::Error, Ace::Herdr::Molecules::BoundedProcess::PostLaunchError
-          unavailable!("worker checkout cannot be observed")
-        end
-
-        def ref_head(cwd, ref)
-          unless ref.is_a?(String) && ref.match?(%r{\Arefs/[a-zA-Z0-9_./-]+\z}) && !ref.include?("..")
-            unavailable!("selected Git ref is invalid")
-          end
-          with_selected_read(cwd) do |selected|
-            head = git(selected, "rev-parse", "--verify", "#{ref}^{commit}").strip
-            unavailable!("selected ref is not a commit") unless head.match?(/\A[0-9a-f]{40}\z/)
-            head
-          end
-        end
-
-        def commit?(cwd, head)
-          exact_head!(head)
-          with_selected_read(cwd) do |selected|
-            git(selected, "rev-parse", "--verify", "--quiet", "#{head}^{commit}", allowed_status: [0, 1], result: true).status.success?
-          end
-        end
-
-        def ancestor?(cwd, ancestor, descendant)
-          exact_head!(ancestor); exact_head!(descendant)
-          with_selected_read(cwd) do |selected|
-            git(selected, "merge-base", "--is-ancestor", ancestor, descendant, allowed_status: [0, 1], result: true).status.success?
-          end
-        end
-
-        private
-
-        def exact_head!(head)
-          unavailable!("selected Git head is invalid") unless head.is_a?(String) && head.match?(/\A[0-9a-f]{40}\z/)
-        end
-
-        def with_selected_read(cwd)
-          absolute!(cwd)
-          unavailable!("selected repository leaves installed worktrees") unless within?(cwd, @root)
-          before = selection(cwd)
-          value = yield before
-          unavailable!("selected repository changed during read") unless before == selection(cwd)
-          value
-        rescue SystemCallError, IOError, Timeout::Error, Ace::Herdr::Molecules::BoundedProcess::PostLaunchError => error
-          unavailable!("selected repository cannot be observed (#{error.class})")
-        end
-
-        def selection(cwd)
-          directory!(cwd)
-          directory!(@common)
-          worktree = cwd
-          loop do
-            break if File.exist?(File.join(worktree, ".git")) || File.symlink?(File.join(worktree, ".git"))
-            unavailable!("worker checkout is unavailable") if worktree == @root
-            worktree = File.dirname(worktree)
-          end
-          marker = File.join(worktree, ".git")
-          metadata = {}
-          git_dir = if File.lstat(marker).directory?
-            directory!(marker)
-            unavailable!("worker belongs to another project") unless marker == @common
-            marker
-          else
-            bytes = regular!(marker, metadata, 4096)
-            match = bytes.match(/\Agitdir: ([^\n\0]+)\n?\z/)
-            unavailable!("worker Git pointer is invalid") unless match
-            selected = File.expand_path(match[1], worktree)
-            unless File.dirname(selected) == File.join(@common, "worktrees")
-              unavailable!("worker Git pointer leaves installed project")
-            end
-            directory!(selected)
-            common = regular!(File.join(selected, "commondir"), metadata, 4096).strip
-            unavailable!("worker common directory differs") unless File.expand_path(common, selected) == @common
-            back = regular!(File.join(selected, "gitdir"), metadata, 4096).strip
-            unavailable!("worker Git backpointer differs") unless back == marker
-            selected
-          end
-          @entries = 0
-          %w[objects refs].each { |name| storage!(File.join(@common, name)) }
-          %w[commondir shallow reftable info/grafts objects/info/alternates objects/info/http-alternates].each do |name|
-            path = File.join(@common, name)
-            unavailable!("worker object storage is redirected") if File.exist?(path) || File.symlink?(path)
-          end
-          regular!(File.join(git_dir, "HEAD"), metadata, 4096)
-          packed = File.join(@common, "packed-refs")
-          storage!(packed) if File.exist?(packed) || File.symlink?(packed)
-          local_refs = File.join(git_dir, "refs")
-          storage!(local_refs) if git_dir != @common && (File.exist?(local_refs) || File.symlink?(local_refs))
-          config!(File.join(@common, "config"), metadata)
-          local = File.join(git_dir, "config.worktree")
-          config!(local, metadata) if File.exist?(local) || File.symlink?(local)
-          {"worktree" => worktree, "git_dir" => git_dir, "metadata" => metadata,
-            "directories" => [cwd, worktree, git_dir, @common].to_h { |path| [path, identity(File.lstat(path))] }}
-        end
-
-        def config!(path, metadata)
-          bytes = regular!(path, metadata, 65_536)
-          output = run(["config", "--no-includes", "--null", "--list", "--file", "/dev/stdin"], stdin: bytes)
-          output.split("\0").each do |entry|
-            key, value = entry.split("\n", 2)
-            if key.start_with?("include.", "includeif.", "extensions.") || key == "core.worktree" ||
-                key == "core.repositoryformatversion" && value != "0"
-              unavailable!("worker Git configuration redirects project storage")
-            end
-          end
-        end
-
-        def git(selected, *argv, allowed_status: [0], result: false)
-          captured = run_result(["--git-dir=#{selected.fetch('git_dir')}", "--work-tree=#{selected.fetch('worktree')}",
-            "-c", "safe.directory=#{selected.fetch('worktree')}", "-c", "core.hooksPath=/dev/null",
-            "-c", "core.fsmonitor=false", "-c", "protocol.allow=never", *argv],
-            environment: {"GIT_COMMON_DIR" => @common, "GIT_OBJECT_DIRECTORY" => File.join(@common, "objects")}, allowed_status: allowed_status)
-          result ? captured : captured.stdout
-        end
-
-        def run(argv, stdin: "", environment: {})
-          run_result(argv, stdin: stdin, environment: environment).stdout
-        end
-
-        def run_result(argv, stdin: "", environment: {}, allowed_status: [0])
-          result = Ace::Herdr::Molecules::BoundedProcess.call(["/usr/bin/git", "--no-pager", *argv],
-            environment: Ace::Assign::Molecules::InstalledJournalRead::ENVIRONMENT.merge(environment), chdir: "/",
-            stdin_data: stdin, timeout_s: remaining, output_limit: 65_536, cleanup_group: true)
-          unavailable!("worker Git read failed or exceeded its bound") unless allowed_status.include?(result.status.exitstatus) && !result.oversized
-          result
-        end
-
-        def regular!(path, metadata, limit)
-          directory!(File.dirname(path))
-          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
-            before = file.stat
-            unavailable!("worker metadata must be a bounded regular file") unless before.file? && before.size <= limit
-            bytes = file.read(limit + 1)
-            unless bytes.bytesize <= limit && stamp(before) == stamp(file.stat) && stamp(before) == stamp(File.lstat(path))
-              unavailable!("worker metadata changed during read")
-            end
-            metadata[path] = [stamp(before), bytes]
-            bytes
-          end
-        end
-
-        def directory!(path)
-          current = path
-          loop do
-            remaining
-            stat = File.lstat(current)
-            unavailable!("worker directory is redirected") unless stat.directory? && !stat.symlink?
-            break if current == "/"
-            current = File.dirname(current)
-          end
-        end
-
-        def storage!(path)
-          remaining
-          @entries += 1
-          unavailable!("worker storage inventory exceeds its bound") if @entries > Ace::Assign::Molecules::InstalledJournalRead::ENTRY_LIMIT
-          stat = File.lstat(path)
-          unavailable!("worker storage is redirected") unless !stat.symlink? && (stat.file? || stat.directory?)
-          Dir.each_child(path) { |name| storage!(File.join(path, name)) } if stat.directory?
-        end
-
-        def absolute!(path)
-          unless path.is_a?(String) && path.bytesize.between?(1, 4096) && !path.include?("\0") &&
-              path.start_with?("/") && File.expand_path(path) == path
-            unavailable!("worker path is invalid")
-          end
-        end
-
-        def within?(path, parent) = path == parent || path.start_with?(parent + "/")
-        def identity(stat) = [stat.dev, stat.ino]
-        def stamp(stat) = [stat.dev, stat.ino, stat.size, stat.mtime, stat.ctime]
-
-        def remaining
-          unless @deadline.is_a?(Numeric) && @deadline.finite? && (left = @deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)).positive?
-            unavailable!("worker observation deadline elapsed")
-          end
-          left
-        end
-
-        def unavailable!(reason)
-          raise Ace::Assign::AttemptErrors::EvidenceUnavailable, reason
-        end
-      end
-    end
-  end
-end