ace-lab 0.9.0 → 0.13.0

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

@@ -1,158 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "yaml"
-require "digest"
-require "ace/assign/atoms/evidence_digest"
-require_relative "grant_resolver"
-
-module Ace
-  module Lab
-    module Molecules
-      # One deployment-owned policy, independent of repository preferences.
-      # The selected grant covers the WHOLE service combination and exact argv.
-      class CommandPolicy
-        PATH = "/etc/lab/ace-lab/project-commands.yml"
-        ID = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}\z/
-        ENV_KEY = /\A[A-Z][A-Z0-9_]{0,63}\z/
-        RESERVED = %w[HOME USER LOGNAME SHELL PATH RUBYOPT RUBYLIB BUNDLE_GEMFILE GEM_HOME GEM_PATH BASH_ENV ENV PYTHONPATH PYTHONHOME PERL5LIB LD_PRELOAD LD_LIBRARY_PATH].freeze
-        attr_reader :project, :launcher
-
-        def self.load(project:)
-          bytes = GrantResolver.read_verified(PATH)
-          raise InvalidConfigurationError, "project commands are not installed" unless bytes && bytes.bytesize <= 65_536
-          new(YAML.safe_load(bytes, aliases: false), project: project)
-        rescue Psych::Exception
-          raise InvalidConfigurationError, "invalid project command policy"
-        end
-
-        def initialize(document, project:)
-          strict!(document, %w[version projects])
-          invalid! unless 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)
-          @project = project
-          @document = JSON.parse(JSON.generate(document))
-          @entry = @document.fetch("projects").fetch(project) { invalid! }
-          strict!(@entry, %w[launcher default_executor default_services executors services commands grants])
-          @launcher = @entry.fetch("launcher")
-          strict!(@launcher, %w[socket_path identity_path])
-          invalid! unless @launcher.values.all? { |value| absolute?(value) }
-          %w[executors services commands].each do |key|
-            value = @entry.fetch(key)
-            invalid! unless value.is_a?(Hash) && value.size <= 64 && value.keys.all? { |id| id.is_a?(String) && ID.match?(id) }
-          end
-          @entry.fetch("executors").each_value do |value|
-            strict!(value, %w[uid gid groups home cwd path environment])
-            invalid! unless %w[uid gid].all? { |key| uid?(value[key]) } &&
-              value["groups"].is_a?(Array) && value["groups"].all? { |gid| uid?(gid) } &&
-              value["groups"].uniq == value["groups"] &&
-              %w[home cwd].all? { |key| absolute?(value[key]) } &&
-              value["path"].is_a?(Array) && !value["path"].empty? && value["path"].all? { |item| absolute?(item) }
-            environment!(value.fetch("environment"))
-          end
-          @entry.fetch("services").each_value do |value|
-            strict!(value, %w[environment secret_references])
-            environment!(value.fetch("environment"))
-            references = value.fetch("secret_references")
-            invalid! unless references.is_a?(Hash) && references.all? { |key, path| env_key?(key) && absolute?(path) }
-          end
-          @entry.fetch("commands").each_value do |value|
-            strict!(value, %w[argv executable_sha256 source purpose])
-            invalid! unless %w[command test].include?(value["purpose"])
-            argv!(value.fetch("argv"))
-            invalid! unless sha?(value.fetch("executable_sha256"))
-            source = value.fetch("source")
-            strict!(source, %w[head tree])
-            invalid! unless source.values.all? { |sha| sha.nil? || (sha.is_a?(String) && sha.match?(/\A[0-9a-f]{40}\z/)) } &&
-              source.values.all?(&:nil?) == source.values.any?(&:nil?)
-            invalid! if value["purpose"] == "test" && source.values.any?(&:nil?)
-          end
-          invalid! unless @entry.fetch("executors").key?(@entry["default_executor"])
-          services!(@entry.fetch("default_services"))
-          invalid! unless @entry["grants"].is_a?(Array) && @entry["grants"].size <= 256
-          @entry["grants"].each do |grant|
-            strict!(grant, %w[kind uid command executor services])
-            invalid! unless %w[operator agent].include?(grant["kind"]) && uid?(grant["uid"]) &&
-              @entry.fetch("commands").key?(grant["command"]) && @entry.fetch("executors").key?(grant["executor"])
-            services!(grant.fetch("services"))
-          end
-          @fingerprint = Ace::Assign::Atoms::EvidenceDigest.digest(@entry)
-          freeze_value(@document)
-        end
-
-        def reader!(uid)
-          deny! unless @entry.fetch("grants").any? { |grant| grant.fetch("uid") == uid }
-          true
-        end
-
-        def select(selection:, peer:)
-          strict!(selection, %w[argv executor services pane])
-          argv!(selection.fetch("argv"))
-          executor_id = selection["executor"] || @entry.fetch("default_executor")
-          executor = @entry.fetch("executors")[executor_id]
-          deny! unless executor
-          requested = selection["services"].nil? ? @entry.fetch("default_services") : selection["services"]
-          services!(requested)
-          selected = requested.uniq.sort
-          matches = @entry.fetch("commands").select { |_name, value| value.fetch("argv") == selection["argv"] }
-          deny! unless matches.size == 1
-          command_id, command = matches.first
-          kind = selection["pane"].nil? ? "operator" : "agent"
-          deny! unless @entry.fetch("grants").any? { |grant|
-            grant.values_at("kind", "uid", "command", "executor") == [kind, peer.fetch("uid"), command_id, executor_id] &&
-              grant.fetch("services").sort == selected }
-          environment = executor.fetch("environment").dup
-          references = {}
-          selected.each do |id|
-            service = @entry.fetch("services").fetch(id)
-            additions = service.fetch("environment")
-            secrets = service.fetch("secret_references")
-            deny! unless (environment.keys & (additions.keys + secrets.keys)).empty? &&
-              (references.keys & (additions.keys + secrets.keys)).empty? && (additions.keys & secrets.keys).empty?
-            environment.merge!(additions)
-            references.merge!(secrets)
-          end
-          definition = {"policy_sha256" => @fingerprint, "project_id" => @project, "command_id" => command_id,
-            "argv" => command.fetch("argv"), "executable_sha256" => command.fetch("executable_sha256"),
-            "source" => command.fetch("source"), "purpose" => command.fetch("purpose"), "executor_id" => executor_id,
-            "executor" => executor.merge("environment" => environment, "groups" => executor.fetch("groups").sort), "services" => selected,
-            "secret_references" => references, "requester" => peer, "requester_kind" => kind,
-            "selection" => selection}
-          invalid! if JSON.generate(definition).bytesize > 8192
-          definition
-        end
-
-        private
-
-        def strict!(value, keys)
-          invalid! unless value.is_a?(Hash) && value.keys.sort == keys.sort
-        end
-        def argv!(value)
-          invalid! unless value.is_a?(Array) && value.size.between?(1, 128) &&
-            value.all? { |item| item.is_a?(String) && item.bytesize <= 4096 && !item.include?("\0") } &&
-            !value.first.empty? && value.sum(&:bytesize) <= 8192
-        end
-        def services!(value)
-          invalid! unless value.is_a?(Array) && value.size <= 64 && value.all? { |id| @entry.fetch("services").key?(id) }
-        end
-        def environment!(value)
-          invalid! unless value.is_a?(Hash) && value.size <= 64 && value.all? { |key, item|
-            env_key?(key) && item.is_a?(String) && item.bytesize <= 4096 && !item.include?("\0") }
-        end
-        def env_key?(key) = key.is_a?(String) && ENV_KEY.match?(key) && !RESERVED.include?(key) && !key.start_with?("GIT_CONFIG_", "BUNDLE_", "LD_", "DYLD_")
-        def absolute?(value) = value.is_a?(String) && value.start_with?("/") && !value.include?("\0") && File.expand_path(value) == value
-        def uid?(value) = value.is_a?(Integer) && value.between?(1, 2**31 - 1)
-        def sha?(value) = value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
-        def invalid! = raise(InvalidConfigurationError, "invalid project command policy")
-        def deny! = raise(SecurityError, "project command selection is not authorized")
-        def freeze_value(value)
-          case value
-          when Hash then value.each { |key, child| key.freeze; freeze_value(child) }
-          when Array then value.each { |child| freeze_value(child) }
-          end
-          value.freeze
-        end
-      end
-    end
-  end
-end

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

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-require "etc"
-
-module Ace
-  module Lab
-    module Molecules
-      # The lab-side HITL delivery authorization (spec 8wq.t.34i): which
-      # authenticated transport may submit correlated answers for a
-      # Captain, derived from the SAME trusted deployment document that
-      # carries the service principals — read through the grant
-      # resolver's verified traversal, never from the cascade. The peer
-      # uid is a KERNEL fact resolved by the HITL boundary; this policy
-      # never trusts a claimed name.
-      class HitlAuthorizer
-        # @param principals [Hash] authorization.principals from the
-        #   trusted document (uid-string or username keys, per-project)
-        # @param transport_uids [Array<Integer>] uids authorized to act
-        #   as the configured transport
-        # @param service_uid [Integer, nil] the trusted HITL service uid
-        def initialize(principals: {}, transport_uids: [], service_uid: nil)
-          @principals = principals || {}
-          @transport_uids = Array(transport_uids)
-          @service_uid = service_uid
-        end
-
-        # Build from the trusted deployment document at a fixed path
-        # (same file the service policy resolves principals from).
-        # @return [HitlAuthorizer]
-        def self.from_trusted_document(path, loader = GrantResolver)
-          document = loader.trusted_document(path)
-          hitl = document["hitl"].is_a?(Hash) ? document["hitl"] : {}
-          principals = document.dig("authorization", "principals")
-          new(
-            principals: principals.is_a?(Hash) ? principals : {},
-            transport_uids: Array(hitl["transport_uids"]),
-            service_uid: hitl["service_uid"]
-          )
-        end
-
-        # @return [Integer, nil] the trusted HITL service identity
-        def service_uid
-          @service_uid.is_a?(Integer) ? @service_uid : nil
-        end
-
-        # The transport may submit a correlated answer from an authorized
-        # Captain when its KERNEL-VERIFIED uid is a configured transport
-        # AND the transport's principal is visible for the request's
-        # project. Unknown identity is an error-shaped refusal, never
-        # permission.
-        def delivery_authorized?(uid:, project_id:)
-          return false unless @transport_uids.include?(uid)
-
-          policy = @principals[uid.to_s]
-          return false unless policy.is_a?(Hash)
-
-          projects = Array(policy["projects"]).map(&:to_s)
-          projects.empty? || projects.include?(project_id.to_s)
-        end
-      end
-    end
-  end
-end

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

@@ -1,131 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-require_relative "service_policy"
-
-module Ace
-  module Lab
-    module Molecules
-      # The scoped ordinary-merge decision/admission resolver (spec 8x3.t.xz9.4,
-      # execution clauses). The deployment-owned YAML authorization file remains
-      # the sole source of truth; this resolver only makes the exact root
-      # authorizations natively executable inside the receiver: one per-request
-      # authorization selector resolves to a typed decision within the closed
-      # refusal-code family — or it refuses. Scoping rules:
-      #
-      # - only `operation: merge` decisions of the ordinary shape resolve;
-      #   anything else (missing reference, shape mismatch, non-merge
-      #   operation, any binding mismatch, expiry) is a typed
-      #   `ordinary_merge_authorization_invalid` decision;
-      # - exact binding match on every closed key; there are NO wildcards,
-      #   defaults, prefix grants or broad grants of any kind — a decision
-      #   authorizes exactly one bound request and nothing else;
-      # - expiry bounds the decision itself.
-      #
-      # Per-request refresh (spec 8x3.t.xz9.5 integration handoff): a
-      # long-lived receiver would otherwise decide every sequential candidate
-      # against its boot-time snapshot of the authorization document. When a
-      # trusted path is installed, every decision re-reads the document
-      # through the trusted loader and resolves against the FRESH grants —
-      # a root-revoked or expired decision fails closed at the next request
-      # without any receiver restart. The refresh is scoped: it reloads and
-      # re-validates the exact-request grant only; it never broadens
-      # authorization beyond the resolved reference.
-      class OrdinaryAdmissionResolver
-        BINDING_KEYS = ServicePolicy::ORDINARY_BINDING_KEYS.freeze
-        DECISION_KEYS = ServicePolicy::ORDINARY_AUTHORIZATION_KEYS.freeze
-        OPERATION = "merge"
-
-        Decision = Struct.new(:authorized?, :decision, :code, :message, keyword_init: true)
-
-        # @param policy_document [Hash] boot-time trusted document (the
-        #   configuration digest is derived from it once, upstream)
-        # @param path [String, nil] trusted policy path to re-read per decision
-        # @param loader [Proc, nil] trusted reader (default: GrantResolver);
-        #   the only override point, for non-privileged test documents
-        def initialize(policy_document, path: nil, loader: nil, proposal_resolver: nil, caller_uid: nil)
-          unless policy_document.is_a?(Hash) && policy_document["authorizations"].is_a?(Hash)
-            raise Ace::Lab::InvalidConfigurationError,
-              "trusted policy document must contain an authorizations mapping"
-          end
-          @authorizations = policy_document.fetch("authorizations")
-          @configuration_digest = ServicePolicy.configuration_digest(policy_document)
-          @path = path
-          @proposal_resolver = proposal_resolver
-          @caller_uid = caller_uid
-          @loader = loader || ->(trusted_path) { GrantResolver.trusted_document(trusted_path) }
-          freeze
-        end
-
-        # Resolve one authorization selector against the exact ordinary merge
-        # request binding. Returns a typed Decision; `authorized?` is true only
-        # for an exact, unexpired, ordinary-merge-shaped match.
-        def decide(reference, binding)
-          authorizations = current_authorizations
-          unless reference.is_a?(String) && reference.match?(ServicePolicy::ID)
-            return refuse("invalid authorization reference")
-          end
-          unless binding.is_a?(Hash) && binding.fetch("operation", nil) == OPERATION
-            return refuse("only the ordinary merge operation is resolvable")
-          end
-          if reference.start_with?("proposal-")
-            return refuse("canonical proposal authority is unavailable") unless @proposal_resolver && @caller_uid.is_a?(Integer)
-            begin
-              decision = @proposal_resolver.call(reference, binding.slice(
-                "operation", "project_id", "assignment_id", "attempt_id", "input_digest", "candidate_head").merge(
-                  "target" => {"resource" => binding.fetch("pr_url"), "artifact_digest" => nil},
-                  "caller_uid" => @caller_uid))
-              return Decision.new(authorized?: true, decision: decision, code: nil, message: nil)
-            rescue Ace::Assign::Error
-              return refuse("canonical proposal does not authorize this exact ordinary merge")
-            end
-          end
-          decision = authorizations[reference]
-          return refuse("authorization reference is unresolved") unless decision.is_a?(Hash)
-          unless DECISION_KEYS.all? { |key| decision.key?(key) }
-            return refuse("authorization reference is not an ordinary merge decision")
-          end
-          unless decision.fetch("operation") == OPERATION
-            return refuse("authorization does not cover the ordinary merge operation")
-          end
-          mismatch = BINDING_KEYS.find { |key| decision.fetch(key) != binding.fetch(key, nil) }
-          return refuse("authorization does not match the exact ordinary merge request") if mismatch
-          begin
-            expired = Time.iso8601(decision.fetch("expires_at").to_s) <= Time.now.utc
-          rescue ArgumentError
-            return refuse("authorization decision has an invalid expiry")
-          end
-          return refuse("authorization has expired") if expired
-          Decision.new(authorized?: true, decision: decision, code: nil, message: nil)
-        end
-
-        private
-
-        # The authorizations mapping the CURRENT decision resolves against:
-        # the boot snapshot when no trusted path is installed, otherwise the
-        # freshly re-read document. A failed trusted re-read fails closed
-        # (InvalidConfigurationError — the unavailable family), never falls
-        # back to the stale snapshot.
-        def current_authorizations
-          return @authorizations unless @path
-          document = @loader.call(@path)
-          unless document.is_a?(Hash) && document["authorizations"].is_a?(Hash)
-            raise Ace::Lab::InvalidConfigurationError,
-              "invalid lab configuration: trusted authorization refresh at #{@path} " \
-              "did not yield an authorizations mapping"
-          end
-          unless ServicePolicy.configuration_digest(document) == @configuration_digest
-            raise Ace::Lab::InvalidConfigurationError,
-              "ordinary receiver configuration changed; restart with the installed configuration"
-          end
-          document.fetch("authorizations")
-        end
-
-        def refuse(message)
-          Decision.new(authorized?: false, decision: nil,
-            code: "ordinary_merge_authorization_invalid", message: message)
-        end
-      end
-    end
-  end
-end

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

@@ -1,262 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "socket"
-require_relative "../errors"
-require_relative "ordinary_socket"
-
-module Ace
-  module Lab
-    module Molecules
-      # The ordinary receiver's serve-side transport (spec 8x3.t.xz9.4 serve
-      # 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 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
-      # fail-closed: the peer receives the closed refusal envelope (or the
-      # connection closes) and nothing is ever dispatched. This is not an
-      # HTTP transport and there is no cross-VM fallback.
-      class OrdinaryListener
-        HANDSHAKE = OrdinarySocket::HANDSHAKE
-        LIMIT = OrdinarySocket::LIMIT
-        DEADLINE_SECONDS = 30
-
-        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
-          @lock_path = lock_path || "#{@socket_path}.lock"
-          @logger = logger
-          @stopping = false
-        end
-
-        # 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(on_ready: nil)
-          acquire_lock!
-          remove_stale_endpoint!
-          @listener = UNIXServer.new(@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)
-          end
-        rescue IOError, Errno::EBADF
-          raise unless @stopping
-        ensure
-          @listener&.close
-          remove_owned_endpoint!
-          @lock&.flock(File::LOCK_UN)
-          @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
-        rescue IOError
-          nil
-        end
-
-        # One bounded connection: verify the peer identity, read one framed
-        # request, answer one framed envelope, close. Fail-closed on every
-        # violation; a dispatch never happens from an unverified frame.
-        def serve_connection(socket)
-          deadline = Time.now.utc + DEADLINE_SECONDS
-          begin
-            verify_peer!(socket)
-            submission = read_request!(socket, deadline)
-            response = @handler.call(submission)
-            write_response_safely(socket, response, deadline)
-            if response.is_a?(Hash) && response["status"] == "ok" && @handler.respond_to?(:execute)
-              begin
-                # 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 => error
-                log_failure("effect", error)
-              end
-            end
-          rescue OrdinaryRefused => e
-            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.
-            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
-              socket.close
-            rescue IOError
-              nil
-            end
-          end
-        end
-
-        class OrdinaryListenerError < ::StandardError; end
-
-        # A verified-connection refusal that still carries a closed envelope.
-        class OrdinaryRefused < OrdinaryListenerError
-          attr_reader :envelope
-
-          def initialize(envelope)
-            @envelope = envelope
-            super(envelope.dig("error", "message").to_s)
-          end
-        end
-
-        private
-
-        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)
-          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, SocketError, NotImplementedError
-          raise OrdinaryListenerError, "peer credentials are unavailable"
-        end
-
-        def read_request!(socket, deadline)
-          header = read_line!(socket, deadline)
-          match = /\A#{Regexp.escape(HANDSHAKE)} (\d{1,5})\n\z/o.match(header)
-          raise OrdinaryListenerError, "request header is invalid" unless match
-          length = Integer(match[1])
-          raise OrdinaryListenerError, "request exceeds the wire bound" if length > LIMIT
-          payload = read_exact!(socket, length, deadline)
-          JSON.parse(payload, allow_duplicate_key: false, create_additions: false, max_nesting: 16)
-        rescue JSON::ParserError
-          raise OrdinaryRefused, refusal_envelope("ordinary_merge_invalid_request",
-            "request document is not valid JSON")
-        end
-
-        def write_response!(socket, response, deadline)
-          payload = JSON.generate(response)
-          raise OrdinaryListenerError, "response exceeds the wire bound" if payload.bytesize > LIMIT
-          frame = "#{HANDSHAKE} #{payload.bytesize}\n#{payload}"
-          written = 0
-          while written < frame.bytesize
-            raise OrdinaryListenerError, "response write deadline expired" if Time.now.utc >= deadline
-            begin
-              written += socket.write_nonblock(frame.byteslice(written..))
-            rescue IO::WaitWritable
-              socket.wait_writable(remaining!(deadline)) or
-                raise OrdinaryListenerError, "response write deadline expired"
-            end
-          end
-        rescue JSON::GeneratorError
-          raise OrdinaryListenerError, "response is not serializable"
-        end
-
-        def refusal_envelope(code, message)
-          {"status" => "error", "error" => {
-            "schema" => "ace.lab.service.ordinary-merge-refusal/v1",
-            "code" => code,
-            "message" => message.to_s.scrub.gsub(/\s+/, " ").strip[0, 512],
-            "request_id" => "unknown",
-            "input_digest" => nil
-          }}
-        end
-
-        def read_line!(socket, deadline)
-          line = +""
-          until line.end_with?("\n")
-            raise OrdinaryListenerError, "request header is unbounded" if line.bytesize > 128
-            line << read_exact!(socket, 1, deadline)
-          end
-          line
-        end
-
-        def read_exact!(socket, length, deadline)
-          buffer = +""
-          while buffer.bytesize < length
-            raise OrdinaryListenerError, "request read deadline expired" if Time.now.utc >= deadline
-            begin
-              chunk = socket.read_nonblock(length - buffer.bytesize)
-              raise OrdinaryListenerError, "peer closed the connection" if chunk.nil?
-              buffer << chunk
-            rescue IO::WaitReadable
-              socket.wait_readable(remaining!(deadline)) or
-                raise OrdinaryListenerError, "request read deadline expired"
-            end
-          end
-          buffer
-        end
-
-        def remaining!(deadline)
-          left = deadline - Time.now.utc
-          raise OrdinaryListenerError, "connection deadline expired" if left <= 0
-          left
-        end
-
-        def acquire_lock!
-          @lock = File.open(@lock_path, 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 Ace::Lab::InvalidConfigurationError, "receiver listener lock differs"
-          end
-          unless @lock.flock(File::LOCK_EX | File::LOCK_NB)
-            raise Ace::Lab::InvalidConfigurationError, "receiver listener already active"
-          end
-        end
-
-        def remove_stale_endpoint!
-          stat = File.lstat(@socket_path)
-          unless stat.socket? && stat.uid == Process.uid
-            raise Ace::Lab::InvalidConfigurationError, "receiver endpoint differs"
-          end
-          File.unlink(@socket_path)
-        rescue Errno::ENOENT
-          nil
-        end
-
-        def remove_owned_endpoint!
-          return unless @endpoint_identity
-          stat = File.stat(@socket_path)
-          File.unlink(@socket_path) if stat.socket? && stat.ino == @endpoint_identity.ino
-        rescue Errno::ENOENT
-          nil
-        end
-      end
-    end
-  end
-end

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

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