ace-lab 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc5e4fcb4d6a771437705ab78e363747cd97d78ce6d32c6a2771b4ef4343af74
-  data.tar.gz: 22de06526b637c15a791944e4594ea94f309e57241ccdc51ae1cd91bbfc98914
+  metadata.gz: 1ad491380d732534c8ae2cbabe68bb796cf997adb19ff6dbdb4b6b66353470c6
+  data.tar.gz: c1ba284a9cf628746450b50e1ecf6dcc03589a771fc6f1d44c2eded6afa24861
 SHA512:
-  metadata.gz: 599fc84b935b3632918f7ab8546ee4f0d7dd59fb8ea0f7933e660176403d19508e468b9153873a132beec1eb89eecbff0341339b01f9da0629f16a94c3300e93
-  data.tar.gz: cd1758fafa5b8c944fd8b0de736b0d8137ed2b4522ffe067c8bbcad5a5be817e6176fd5a571d6410fc144cf03d88bccbb91d5c7872e9b6c8b29f85066f3c4c81
+  metadata.gz: d6c8605dabf1a3f4bdac9f39a8afeac4c606c30832380f4b93921fc91d9bcd3ac364d1056fbb426130d25bf23410abd29cbd1dd80ec31ad99a563fe224f2c3bc
+  data.tar.gz: d8ca70d0072169a318b7bf2cc57d291f6d9db14250c5af774920e0fb212735570ede41fdc360c1e099f8a41d4de43355bd1e7e6a7aca8a86fef8a21289ba04de

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-14
+
+### Added
+
+- Add the ordinary fixed merge producer mode (`ace-lab service request/status --mode ordinary-merge`) per xz9.4: durable-once admission that issues the opaque reference only through the committed journal record, canonical SHA-256 request digests over the full eight-field binding, identical-replay acknowledgment, authorization/binding conflict refusals, read-only status, and terminal receipts bound to the admitted record and its execution identity.
+
 ## [0.5.2] - 2026-10-11
 
 ### Changed

data/lib/ace/lab/cli/commands/service.rb

@@ -2,8 +2,10 @@
 
 require "json"
 require "ace/support/cli"
+require "ace/assign"
 require_relative "support"
 require_relative "../../organisms/protected_service_request"
+require_relative "../../organisms/ordinary_merge_request"
 
 module Ace
   module Lab
@@ -20,7 +22,7 @@ module Ace
             end
 
             def protected_refusal(error)
-              code = error.is_a?(ArgumentError) || error.is_a?(SecurityError) ? "protected_service_refused" : "protected_service_unavailable"
+              code = (error.is_a?(ArgumentError) || error.is_a?(SecurityError)) ? "protected_service_refused" : "protected_service_unavailable"
               message = error.is_a?(JSON::ParserError) ? "protected installed selection unavailable" : error.message.to_s.scrub[0, 512]
               emit({"status" => "error", "error" => {"code" => code, "message" => message}})
             end
@@ -49,6 +51,8 @@ module Ace
             option :authorization, type: :string, required: true, desc: "Exact authorization reference"
             option :request_id, type: :string, required: true, desc: "Idempotency key"
             option :dry_run, type: :boolean, desc: "Validate without claiming or executing"
+            option :mode, type: :string, desc: "ordinary-merge selects the ordinary fixed merge producer"
+            option :queue_entry, type: :string, desc: "Original queue entry (ordinary merge)"
 
             option :mapping, type: :string, desc: "Original protected mapping ID"
             option :scope, type: :string, desc: "Original hierarchical prepared scope"
@@ -59,6 +63,26 @@ module Ace
 
             def call(project:, assignment:, attempt:, operation:, input:, authorization:, request_id:, **options)
               reject_identity_flags!(options)
+              mode = options[:mode]
+              if mode && mode != Organisms::OrdinaryMergeRequest::MODE
+                return emit(Organisms::OrdinaryMergeRequest.refusal_envelope("ordinary_merge_invalid_request",
+                  "unknown service mode", request_id: request_id, input_digest: nil))
+              end
+              if mode
+                begin
+                  return emit(ordinary_request(project: project, assignment: assignment, attempt: attempt,
+                    queue_entry: options[:queue_entry], operation: operation, input: input,
+                    authorization: authorization, request_id: request_id, **options))
+                rescue Ace::Assign::AttemptErrors::EvidenceUnavailable, Ace::Lab::InvalidConfigurationError => e
+                  # Infra failures (unreadable canonical evidence, malformed
+                  # installed configuration, unavailable topology) are the
+                  # caller-side blocker, never a raw crash and never a durable
+                  # reference (review r1 finding B).
+                  return emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                    "ordinary_merge_unavailable", e.message, request_id: request_id, input_digest: nil
+                  ))
+                end
+              end
               selected = protected_service.selected?(options)
               if selected
                 return emit(protected_service.request(project: project, assignment: assignment, attempt: attempt,
@@ -68,9 +92,21 @@ module Ace
                 operation: operation, input_path: input, authorization: authorization,
                 request_id: request_id, dry_run: options[:dry_run]))
             rescue ArgumentError, Ace::Assign::Error, Ace::Git::Error, Ace::Runtime::RuntimeUnavailableError, JSON::ParserError, SecurityError, KeyError, SystemCallError => error
-              raise if selected == false
+              raise if selected == false || mode
               protected_refusal(error)
             end
+
+            private
+
+            def ordinary_producer
+              @ordinary_producer ||= Organisms::OrdinaryMergeRequest.new
+            end
+
+            # The ordinary refusal envelope is emitted exactly as received;
+            # it is classified for the non-zero exit like every refusal.
+            def ordinary_request(**arguments)
+              ordinary_producer.request(**arguments)
+            end
           end
 
           class Status < Ace::Support::Cli::Command
@@ -81,6 +117,9 @@ module Ace
             desc "Read the authoritative outcome of a service request"
             option :request, type: :string, required: true, desc: "Request ID"
             option :format, type: :string, desc: "Output format (json only)"
+            option :mode, type: :string, desc: "ordinary-merge selects the read-only ordinary status"
+            option :reference, type: :string, desc: "Opaque ordinary merge reference"
+            option :queue_entry, type: :string, desc: "Original queue entry (ordinary merge)"
 
             option :project, type: :string, desc: "Original project ID"
             option :assignment, type: :string, desc: "Original assignment ID"
@@ -95,16 +134,40 @@ module Ace
 
             def call(request:, **options)
               reject_identity_flags!(options)
-              ensure_json_format!(options)
+              mode = options[:mode]
+              if mode && mode != Organisms::OrdinaryMergeRequest::MODE
+                return emit(Organisms::OrdinaryMergeRequest.refusal_envelope("ordinary_merge_invalid_request",
+                  "unknown service mode", request_id: request, input_digest: nil,
+                  schema: Ace::Assign::Atoms::FixedMergeSchemas::STATUS_ERROR_SCHEMA_ID))
+              end
+              if mode
+                ensure_json_format!(options)
+                begin
+                  return emit(ordinary_producer.status(project: options[:project], assignment: options[:assignment],
+                    attempt: options[:attempt], queue_entry: options[:queue_entry], reference: options[:reference],
+                    request: request, input_digest: options[:input_digest], **options))
+                rescue Ace::Assign::AttemptErrors::EvidenceUnavailable, Ace::Lab::InvalidConfigurationError => e
+                  return emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                    "ordinary_merge_unavailable", e.message, request_id: request, input_digest: nil,
+                    schema: Ace::Assign::Atoms::FixedMergeSchemas::STATUS_ERROR_SCHEMA_ID
+                  ))
+                end
+              end
               selected = protected_service.selected?(options)
               if selected
                 return emit(protected_service.status(request_id: request, **options))
               end
               emit(service.status(request_id: request))
             rescue ArgumentError, Ace::Assign::Error, Ace::Git::Error, Ace::Runtime::RuntimeUnavailableError, JSON::ParserError, SecurityError, KeyError, SystemCallError => error
-              raise if selected == false
+              raise if selected == false || mode
               protected_refusal(error)
             end
+
+            private
+
+            def ordinary_producer
+              @ordinary_producer ||= Organisms::OrdinaryMergeRequest.new
+            end
           end
         end
       end

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

@@ -0,0 +1,129 @@
+# 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 SO_PEERCRED — 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 = Socket.new(:UNIX, :STREAM, 0)
+          begin
+            socket.connect(Addrinfo.unix(@socket_path))
+            verify_peer!(socket)
+            write_all!(socket, "#{HANDSHAKE} #{payload.bytesize}\n#{payload}")
+            response = read_response!(socket)
+          rescue OrdinaryUnavailable
+            raise
+          rescue SystemCallError, IOError => 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)
+          credentials = socket.getsockopt(:SOCKET, :PEERCRED)
+          # struct ucred is {pid, uid, gid} on Linux; the producer binds the
+          # receiver to its installed UID and nothing else.
+          _peer_pid, peer_uid, = credentials.unpack("L3")
+          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/service_policy.rb

@@ -15,6 +15,7 @@ module Ace
         ID = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/
 
         def initialize(document, proposal_resolver = nil)
+          @document = document
           @operations = document.fetch("operations", {})
           @authorizations = document.fetch("authorizations", {})
           @proposal_resolver = proposal_resolver
@@ -23,6 +24,10 @@ module Ace
           end
         end
 
+        # The trusted installation document as loaded; the ordinary producer
+        # binds its configuration digest to these exact bytes.
+        attr_reader :document
+
         def operation!(name, project:, service_id:)
           raise ArgumentError, "invalid operation name" unless name.to_s.match?(NAME)
           operation = @operations[name]
@@ -101,6 +106,72 @@ module Ace
           decision
         end
 
+        # ---- ordinary fixed merge admission policy (spec 8x3.t.xz9.4) ------
+        #
+        # The installed ordinary section is the separately configured
+        # ordinary receiver mapping and admission policy. It supplies
+        # identity and placement only: the caller selects no endpoint,
+        # credential or receiver. An absent project section or a disabled
+        # admission flag is rollback: new admission is unavailable while
+        # canonical records and read-only status stay preserved.
+        ORDINARY_SECTION_KEYS = %w[projects].freeze
+        ORDINARY_PROJECT_KEYS = %w[receiver_id socket_path receiver_uid principal admission].freeze
+        ORDINARY_AUTHORIZATION_KEYS = %w[operation project_id assignment_id attempt_id queue_entry
+          input_digest forge pr_url head_repository head_ref candidate_head base_repository
+          base_ref expected_base_head expires_at].freeze
+        # expires_at bounds the decision itself; it is never exact-matched
+        # against the request binding, which carries no expiry.
+        ORDINARY_BINDING_KEYS = ORDINARY_AUTHORIZATION_KEYS - %w[expires_at].freeze
+
+        def ordinary_receiver!(project)
+          section = @document["ordinary"]
+          return nil unless section.is_a?(Hash)
+          validate_ordinary_section!(section)
+          entry = section.fetch("projects")[project.to_s]
+          return nil unless entry.is_a?(Hash)
+          entry
+        end
+
+        # The ordinary admission decision: exact-match on every closed
+        # binding key, like authorize!, but over the ordinary request
+        # identity (forge/PR/repository/ref) instead of execution selectors.
+        def authorize_ordinary!(reference, binding)
+          raise ArgumentError, "invalid authorization reference" unless reference.to_s.match?(ID)
+          decision = @authorizations[reference]
+          raise SecurityError, "authorization reference is unresolved" unless decision.is_a?(Hash)
+          unless ORDINARY_AUTHORIZATION_KEYS.all? { |key| decision.key?(key) }
+            raise SecurityError, "authorization reference is not an ordinary merge decision"
+          end
+          unless ORDINARY_BINDING_KEYS.all? { |key| decision[key] == binding[key] }
+            raise SecurityError, "authorization does not match the exact ordinary merge request"
+          end
+          raise SecurityError, "authorization has expired" if parse_time(decision["expires_at"]) <= Time.now.utc
+          decision
+        end
+
+        def validate_ordinary_section!(section)
+          unless (section.keys - ORDINARY_SECTION_KEYS).empty? && section["projects"].is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError, "ordinary section must map projects"
+          end
+          section.fetch("projects").each do |project, entry|
+            unless project.is_a?(String) && project.match?(ID) && entry.is_a?(Hash) &&
+                (entry.keys - ORDINARY_PROJECT_KEYS).empty?
+              raise Ace::Lab::InvalidConfigurationError, "ordinary project section is invalid"
+            end
+            unless entry["receiver_id"].is_a?(String) && entry["receiver_id"].match?(ID) &&
+                entry["socket_path"].is_a?(String) && entry["socket_path"].start_with?("/") &&
+                entry["receiver_uid"].is_a?(Integer) && entry["receiver_uid"] >= 0 &&
+                entry["principal"].is_a?(String) && !entry["principal"].empty?
+              raise Ace::Lab::InvalidConfigurationError, "ordinary receiver mapping is incomplete"
+            end
+            admission = entry.fetch("admission", "enabled")
+            unless %w[enabled disabled].include?(admission)
+              raise Ace::Lab::InvalidConfigurationError, "ordinary admission flag is invalid"
+            end
+          end
+          true
+        end
+
         # Inspection never renews effect permission or selects effect argv.
         def inspection!(name, project:, service_id:, executor_uid:)
           raise ArgumentError, "invalid inspection operation" unless name.is_a?(String) && name.match?(NAME)

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

@@ -0,0 +1,422 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "open3"
+require_relative "protected_service_request"
+require_relative "../molecules/ordinary_socket"
+require "ace/assign/atoms/fixed_merge_schemas"
+
+module Ace
+  module Lab
+    module Organisms
+      # The ordinary fixed merge admission producer (spec 8x3.t.xz9.4). One
+      # mode of the maintained `service request/status` vocabulary: it
+      # canonicalizes the immutable request binding, authenticates the
+      # verified project overseer against the installed ordinary mapping,
+      # resolves the named queue entry and attempt, transports the request
+      # to the configured ordinary receiver, and emits the adopted ace-lab
+      # envelopes — never a second protocol. Refusals are pre-effect and
+      # carry no durable reference; unavailability is a caller-side blocker;
+      # the canonical Assign attempt/evidence state stays the sole
+      # queue/effect record, so this class owns no ledger.
+      class OrdinaryMergeRequest
+        MODE = "ordinary-merge"
+        OPERATION = "merge"
+
+        # The closed pre-effect refusal codes (exhaustive pre-effect mapping).
+        CODES = %w[ordinary_merge_invalid_request ordinary_merge_unauthenticated
+          ordinary_merge_forbidden ordinary_merge_selection_mismatch
+          ordinary_merge_authorization_invalid ordinary_merge_provenance_mismatch
+          ordinary_merge_target_changed ordinary_merge_evidence_invalid
+          ordinary_merge_request_conflict ordinary_merge_unavailable].freeze
+
+        # Selector keys this producer accepts; anything else — including the
+        # protected mapping/scope/service/generation selectors and any
+        # executable/argv/UID/socket/evidence-path/credential/token selector
+        # — refuses before effect.
+        REQUEST_KEYS = %i[project assignment attempt queue_entry operation input authorization
+          request_id mode].freeze
+        STATUS_KEYS = %i[project assignment attempt queue_entry reference request input_digest
+          mode format].freeze
+
+        ID = Molecules::ServicePolicy::ID
+
+        def initialize(topology: nil, policy: nil, coordinator: nil, repo_root: nil, ingress: nil)
+          @topology = topology || TopologyService.from_config
+          @repo_root = repo_root || git_toplevel
+          @coordinator = coordinator ||
+            Ace::Assign::Organisms::AttemptCoordinator.new(repo_root: @repo_root)
+          @policy = policy || Molecules::ServicePolicy.new(
+            Molecules::GrantResolver.trusted_document(Ace::Lab.authorization_path)
+          )
+          @ingress = ingress
+        end
+
+        def request(project:, assignment:, attempt:, queue_entry:, operation:, input:,
+          authorization:, request_id:, **options)
+          digest = nil
+          unless (options.keys - REQUEST_KEYS).empty?
+            invalid!("unknown request selector: #{unknown(options.keys, REQUEST_KEYS)}", request_id)
+          end
+          invalid!("operation must be merge", request_id) unless operation == OPERATION
+          identifiers!(project: project, assignment: assignment, attempt: attempt,
+            queue_entry: queue_entry, request_id: request_id)
+          unless authorization.is_a?(String) && authorization.match?(ID)
+            invalid!("invalid authorization reference", request_id)
+          end
+          document = load_request_document(input, request_id)
+          validate_document!(document, request_id)
+          digest = input_digest(project: project, assignment: assignment, attempt: attempt,
+            queue_entry: queue_entry, authorization: authorization, request_id: request_id,
+            document: document)
+          principal = authenticate!(project)
+          existing = @coordinator.fixed_merge_record(request_id)
+          if existing
+            return ack_envelope(existing) if exact_replay?(existing, project: project,
+              assignment: assignment, attempt: attempt, queue_entry: queue_entry,
+              authorization: authorization, digest: digest)
+            conflict!("request ID already exists with a different binding", request_id, digest)
+          end
+          receiver = receiver_mapping!(project)
+          resolve_selection!(project: project, assignment: assignment, attempt: attempt,
+            queue_entry: queue_entry)
+          authorize!(authorization, project: project, assignment: assignment, attempt: attempt,
+            queue_entry: queue_entry, document: document, digest: digest)
+          verify_candidate_head!(document)
+          submission = {"project_id" => project, "assignment_id" => assignment,
+                        "attempt_id" => attempt, "queue_entry" => queue_entry, "operation" => OPERATION,
+                        "authorization" => authorization, "request_id" => request_id,
+                        "input_digest" => digest, "request" => document, "principal" => principal,
+                        "receiver_id" => receiver.fetch("receiver_id"),
+                        "configuration_sha256" => receiver.fetch("configuration_sha256")}
+          response = deliver(receiver, submission)
+          normalize_response(response, request_id: request_id, input_digest: digest)
+        rescue OrdinaryMergeRefusal => e
+          self.class.refusal_envelope(e.code, e.detail, request_id: e.request_id || request_id,
+            input_digest: e.input_digest || digest)
+        rescue Ace::Assign::AttemptErrors::AuthorizationConflict => e
+          self.class.refusal_envelope("ordinary_merge_authorization_invalid", e.message,
+            request_id: request_id, input_digest: digest)
+        rescue Ace::Assign::AttemptErrors::Conflict => e
+          self.class.refusal_envelope("ordinary_merge_request_conflict", e.message,
+            request_id: request_id, input_digest: digest)
+        rescue Molecules::OrdinarySocket::OrdinaryUnavailable => e
+          self.class.refusal_envelope("ordinary_merge_unavailable", e.message,
+            request_id: request_id, input_digest: digest)
+        rescue Ace::Assign::AttemptErrors::EvidenceUnavailable, Ace::Lab::InvalidConfigurationError => e
+          # Canonical evidence or installed configuration is unreadable: a
+          # caller-side blocker (endpoint/configuration failed), never a
+          # refusal and never a durable reference.
+          self.class.refusal_envelope("ordinary_merge_unavailable", e.message,
+            request_id: request_id, input_digest: digest)
+        end
+
+        # Read-only status: resolve the opaque reference against the canonical
+        # record with every selector; performs no dispatch, retry,
+        # authorization refresh or selector repair. Read-only status survives
+        # rollback and receiver downtime because the canonical Assign state —
+        # never a receiver — owns the record.
+        def status(project:, assignment:, attempt:, queue_entry:, reference:, request:,
+          input_digest:, **options)
+          unless (options.keys - STATUS_KEYS).empty?
+            return status_error(self.class.refusal_envelope("ordinary_merge_invalid_request",
+              "unknown status selector: #{unknown(options.keys, STATUS_KEYS)}",
+              request_id: request, input_digest: nil,
+              schema: Ace::Assign::Atoms::FixedMergeSchemas::STATUS_ERROR_SCHEMA_ID))
+          end
+          identifiers!(project: project, assignment: assignment, attempt: attempt,
+            queue_entry: queue_entry, request_id: request)
+          unless options[:format] == "json"
+            invalid!("status requires --format json", request)
+          end
+          unless reference.is_a?(String) && Ace::Assign::Molecules::FixedEffectReference.valid?(reference)
+            invalid!("invalid reference", request)
+          end
+          unless input_digest.is_a?(String) && input_digest.match?(/\A[0-9a-f]{64}\z/)
+            invalid!("invalid input digest", request)
+          end
+          authenticate!(project)
+          record = @coordinator.fixed_merge_status(reference: reference, request_id: request,
+            project_id: project, assignment_id: assignment, attempt_id: attempt,
+            queue_entry: queue_entry, input_digest: input_digest)
+          # Unknown or mismatched references answer identically, without
+          # revealing whether another project holds the reference.
+          return status_error(selection_error) unless record
+          {"status" => "ok", "data" => {
+            "schema" => Ace::Assign::Atoms::FixedMergeSchemas::STATUS_SCHEMA_ID,
+            "state" => record.fetch("state"),
+            "reference" => record.fetch("reference"),
+            "request_id" => record.fetch("request_id"),
+            "input_digest" => record.fetch("input_digest"),
+            "receipt" => %w[pending uncertain].include?(record.fetch("state")) ? nil : record["receipt"]
+          }}
+        rescue OrdinaryMergeRefusal => e
+          status_error(self.class.refusal_envelope(e.code, e.detail, request_id: request, input_digest: nil,
+            schema: Ace::Assign::Atoms::FixedMergeSchemas::STATUS_ERROR_SCHEMA_ID))
+        rescue Ace::Assign::AttemptErrors::EvidenceUnavailable, Ace::Lab::InvalidConfigurationError => e
+          # Canonical state or installed configuration unreadable: the status
+          # command degrades to the caller-side blocker envelope, never to a
+          # fabricated state or a raw crash.
+          status_error(self.class.refusal_envelope("ordinary_merge_unavailable", e.message,
+            request_id: request, input_digest: nil,
+            schema: Ace::Assign::Atoms::FixedMergeSchemas::STATUS_ERROR_SCHEMA_ID))
+        end
+
+        # ---- envelope composition (the adopted ace-lab vocabulary) ---------
+
+        def ack_envelope(record)
+          {"status" => "ok", "data" => {
+            "schema" => Ace::Assign::Atoms::FixedMergeSchemas::ACK_SCHEMA_ID,
+            "type" => "accepted",
+            "request_id" => record.fetch("request_id"),
+            "input_digest" => record.fetch("input_digest"),
+            "reference" => record.fetch("reference")
+          }}
+        end
+
+        def self.sanitize(message)
+          cleaned = message.to_s.scrub.gsub(/\s+/, " ").strip[0, 512]
+          cleaned.empty? ? "ordinary merge request refused" : cleaned
+        end
+
+        # Envelope composition is instance-independent; the CLI reuses it for
+        # mode-selection refusals before any producer exists.
+        def self.refusal_envelope(code, message, request_id:, input_digest:,
+          schema: Ace::Assign::Atoms::FixedMergeSchemas::REFUSAL_SCHEMA_ID)
+          raise ArgumentError, "unknown ordinary merge refusal code" unless CODES.include?(code)
+          echo = request_id.to_s[0, 256]
+          echo = "unknown" if echo.empty?
+          {"status" => "error", "error" => {
+            "schema" => schema,
+            "code" => code,
+            "message" => sanitize(message),
+            "request_id" => echo,
+            "input_digest" => input_digest
+          }}
+        end
+
+        private
+
+        # The immutable binding digest — spec ruling r4: lowercase hex SHA-256
+        # over the canonical JSON (recursively key-sorted, compact, UTF-8) of
+        # the full eight-field binding. Computed once here at admission; the
+        # same shared implementation re-derives it for replay and receipt
+        # verification, so the pair can never diverge.
+        def input_digest(project:, assignment:, attempt:, queue_entry:, authorization:,
+          request_id:, document:)
+          Ace::Assign::Atoms::FixedMergeSchemas.canonical_request_digest(
+            project: project, assignment: assignment, attempt: attempt,
+            queue_entry: queue_entry, authorization: authorization,
+            request_id: request_id, input: document
+          )
+        end
+
+        def validate_document!(document, request_id)
+          Ace::Assign::Atoms::FixedMergeSchemas.validate_request!(document)
+          Ace::Assign::Atoms::FixedMergeSchemas.require_request_joins!(document)
+        rescue Ace::Assign::Atoms::FixedMergeSchemas::SchemaError => e
+          invalid!(e.message, request_id)
+        end
+
+        # The verified local process owner is the only caller identity; it
+        # must be the configured ordinary project overseer principal.
+        def authenticate!(project)
+          identities = Molecules::CallerAuthorizer.local_identity
+          refused("ordinary_merge_unauthenticated", "verified local identity is unavailable") if identities.empty?
+          receiver = @policy.ordinary_receiver!(project)
+          unless receiver.is_a?(Hash) && identities.include?(receiver.fetch("principal"))
+            refused("ordinary_merge_forbidden",
+              "authenticated principal is not the configured ordinary project overseer")
+          end
+          receiver.fetch("principal")
+        end
+
+        # The installed ordinary section supplies identity and placement only.
+        # A disabled or absent admission mapping is rollback: a caller-side
+        # blocker that never redirects ordinary callers and never deletes the
+        # canonical records — read-only status stays fully available.
+        def receiver_mapping!(project)
+          receiver = @policy.ordinary_receiver!(project)
+          if receiver.nil? || receiver.fetch("admission", "enabled") != "enabled"
+            raise Molecules::OrdinarySocket::OrdinaryUnavailable,
+              "ordinary merge admission is not available in the installed configuration"
+          end
+          receiver.merge("configuration_sha256" => Atoms::ServiceInput.digest(@policy.document))
+        end
+
+        def resolve_selection!(project:, assignment:, attempt:, queue_entry:)
+          @coordinator.service_attempt("assignment_id" => assignment, "attempt_id" => attempt,
+            "project_id" => project)
+        rescue Ace::Assign::AttemptErrors::NotFound, Ace::Assign::AttemptErrors::ReceiptRejected,
+          Ace::Assign::AttemptErrors::InvalidState => e
+          refused("ordinary_merge_selection_mismatch", e.message)
+        end
+
+        def authorize!(authorization, project:, assignment:, attempt:, queue_entry:, document:, digest:)
+          binding = {"operation" => OPERATION, "project_id" => project,
+                     "assignment_id" => assignment, "attempt_id" => attempt, "queue_entry" => queue_entry,
+                     "input_digest" => digest, "forge" => document.fetch("forge"),
+                     "pr_url" => document.fetch("pr_url"), "head_repository" => document.fetch("head_repository"),
+                     "head_ref" => document.fetch("head_ref"), "candidate_head" => document.fetch("candidate_head"),
+                     "base_repository" => document.fetch("base_repository"), "base_ref" => document.fetch("base_ref"),
+                     "expected_base_head" => document.fetch("expected_base_head")}
+          @policy.authorize_ordinary!(authorization, binding)
+        rescue SecurityError => e
+          # Spec table (ruling r4): the authorization decision or reference is
+          # invalid for this request — missing, expired, revoked, out of scope,
+          # bound to another operation/project/PR/head, or not an ordinary
+          # merge decision at all. Authorization-decision mismatches NEVER use
+          # provenance_mismatch; that code is reserved for registered
+          # provenance drift verified by the receiver (and relayed verbatim).
+          refused("ordinary_merge_authorization_invalid", e.message)
+        end
+
+        def verify_candidate_head!(document)
+          unless current_head == document.fetch("candidate_head")
+            refused("ordinary_merge_target_changed", "candidate head moved from the immutable request")
+          end
+        end
+
+        def deliver(receiver, submission)
+          ingress = @ingress || default_ingress(receiver)
+          ingress.call(submission: submission)
+        end
+
+        def default_ingress(receiver)
+          socket = Molecules::OrdinarySocket.new(socket_path: receiver.fetch("socket_path"),
+            receiver_uid: receiver.fetch("receiver_uid"))
+          ->(submission:) { socket.submit(submission) }
+        end
+
+        # A valid receiver acknowledgment is relayed exactly; a valid receiver
+        # refusal is relayed with its closed code; anything else is a lost or
+        # unauthenticated response — a caller-side blocker, never a proven
+        # refusal and never a resubmission authorization.
+        def normalize_response(response, request_id:, input_digest:)
+          unless response.is_a?(Hash) && (response.keys - %w[status data error]).empty? &&
+              %w[ok error].include?(response["status"])
+            raise Molecules::OrdinarySocket::OrdinaryUnavailable, "receiver response envelope is invalid"
+          end
+          return normalize_ack(response, request_id: request_id, input_digest: input_digest) if
+            response.fetch("status") == "ok"
+          normalize_refusal(response, request_id: request_id, input_digest: input_digest)
+        end
+
+        def normalize_ack(response, request_id:, input_digest:)
+          data = response.fetch("data") { {} }
+          expected = %w[schema type request_id input_digest reference]
+          digest = data["input_digest"]
+          unless data.is_a?(Hash) && (data.keys - expected).empty? &&
+              expected.all? { |key| data[key].is_a?(String) && !data[key].empty? } &&
+              data.fetch("schema") == Ace::Assign::Atoms::FixedMergeSchemas::ACK_SCHEMA_ID &&
+              data.fetch("type") == "accepted" && data.fetch("request_id") == request_id &&
+              digest == input_digest && digest.match?(/\A[0-9a-f]{64}\z/) &&
+              Ace::Assign::Molecules::FixedEffectReference.valid?(data.fetch("reference"))
+            raise Molecules::OrdinarySocket::OrdinaryUnavailable,
+              "receiver acknowledgment is invalid or lost before durability could be confirmed"
+          end
+          {"status" => "ok", "data" => data.slice(*expected)}
+        end
+
+        def normalize_refusal(response, request_id:, input_digest:)
+          error = response.fetch("error") { {} }
+          expected = %w[schema code message request_id input_digest]
+          valid = error.is_a?(Hash) && (error.keys - expected).empty? &&
+            error.fetch("schema") == Ace::Assign::Atoms::FixedMergeSchemas::REFUSAL_SCHEMA_ID &&
+            CODES.include?(error.fetch("code")) &&
+            error.fetch("message").is_a?(String) && !error.fetch("message").empty? &&
+            error.fetch("message").length <= 512 &&
+            error.fetch("request_id") == request_id &&
+            (error.fetch("input_digest").nil? || error.fetch("input_digest") == input_digest)
+          unless valid
+            raise Molecules::OrdinarySocket::OrdinaryUnavailable, "receiver refusal envelope is invalid"
+          end
+          {"status" => "error", "error" => error.slice(*expected)}
+        end
+
+        def selection_error
+          self.class.refusal_envelope("ordinary_merge_selection_mismatch",
+            "reference and selectors do not match a canonical ordinary merge record",
+            request_id: nil, input_digest: nil,
+            schema: Ace::Assign::Atoms::FixedMergeSchemas::STATUS_ERROR_SCHEMA_ID)
+        end
+
+        def status_error(envelope)
+          {"status" => "error", "error" => envelope.fetch("error")}
+        end
+
+        def identifiers!(project:, assignment:, attempt:, queue_entry:, request_id:)
+          {"project" => project, "assignment" => assignment, "attempt" => attempt,
+           "queue_entry" => queue_entry, "request_id" => request_id}.each do |name, value|
+            invalid!("invalid #{name} ID", request_id) unless value.is_a?(String) && value.match?(ID)
+          end
+        end
+
+        def load_request_document(input, request_id)
+          Atoms::ServiceInput.load(input)
+        rescue ArgumentError => e
+          invalid!(e.message, request_id)
+        end
+
+        def unknown(keys, allowed)
+          (keys - allowed).sort.join(", ")
+        end
+
+        # A pre-effect refusal carries its closed code, sanitized message and
+        # the request binding for the wire envelope — never a reference.
+        OrdinaryMergeRefusal = Class.new(::StandardError) do
+          attr_reader :code, :detail, :request_id, :input_digest
+
+          def initialize(code, detail, request_id: nil, input_digest: nil)
+            @code = code
+            @detail = detail
+            @request_id = request_id
+            @input_digest = input_digest
+            super(detail)
+          end
+        end
+
+        def invalid!(message, request_id)
+          raise OrdinaryMergeRefusal.new("ordinary_merge_invalid_request", message, request_id: request_id)
+        end
+
+        def conflict!(message, request_id, digest)
+          raise OrdinaryMergeRefusal.new("ordinary_merge_request_conflict", message,
+            request_id: request_id, input_digest: digest)
+        end
+
+        # A replay must match every caller-supplied immutable field: command
+        # selectors, authorization, input byte meaning and canonical digest.
+        def exact_replay?(existing, project:, assignment:, attempt:, queue_entry:,
+          authorization:, digest:)
+          existing["state"] &&
+            existing.slice("project_id", "assignment_id", "attempt_id", "queue_entry",
+              "authorization", "input_digest") == {
+                "project_id" => project, "assignment_id" => assignment, "attempt_id" => attempt,
+                "queue_entry" => queue_entry, "authorization" => authorization, "input_digest" => digest
+              }
+        end
+
+        def refused(code, message)
+          raise OrdinaryMergeRefusal.new(code, message)
+        end
+
+        # The git toplevel (not a package directory that happens to hold a
+        # Rakefile) bounds candidate-head verification for nested invocations.
+        def git_toplevel
+          out, status = Open3.capture2("git", "rev-parse", "--show-toplevel")
+          (status&.success? ? out.strip : Dir.pwd)
+        rescue Errno::ENOENT
+          Dir.pwd
+        end
+
+        def current_head
+          out, _stderr, status = Open3.capture3("git", "rev-parse", "HEAD", chdir: @repo_root)
+          refused("ordinary_merge_target_changed", "candidate head is unavailable") unless status.success?
+          out.strip
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Lab
-    VERSION = "0.5.2"
+    VERSION = "0.6.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-lab
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-runtime
@@ -71,28 +71,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.67'
+        version: '0.68'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.67'
+        version: '0.68'
 - !ruby/object:Gem::Dependency
   name: ace-hitl
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: '0.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: '0.15'
 - !ruby/object:Gem::Dependency
   name: ace-support-test-helpers
   requirement: !ruby/object:Gem::Requirement
@@ -222,6 +222,7 @@ files:
 - lib/ace/lab/molecules/grant_resolver.rb
 - lib/ace/lab/molecules/hitl_authorizer.rb
 - lib/ace/lab/molecules/inventory_query.rb
+- lib/ace/lab/molecules/ordinary_socket.rb
 - lib/ace/lab/molecules/protected_cleanup_owner_admission.rb
 - lib/ace/lab/molecules/protected_cleanup_owner_client.rb
 - lib/ace/lab/molecules/protected_cleanup_owner_identity.rb
@@ -232,6 +233,7 @@ files:
 - lib/ace/lab/molecules/service_policy.rb
 - lib/ace/lab/molecules/topology_loader.rb
 - lib/ace/lab/organisms/authority_composition.rb
+- lib/ace/lab/organisms/ordinary_merge_request.rb
 - lib/ace/lab/organisms/protected_cleanup_owner.rb
 - lib/ace/lab/organisms/protected_service_client.rb
 - lib/ace/lab/organisms/protected_service_listener.rb