ace-git 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecb7e3224f26cacff289f62d5199d90740ee07a4fbaa378649fc948133e6d05c
-  data.tar.gz: 13ac60da2a81dda68242bc0c9f5f21f5e44f764562f24877426e873b59137bbf
+  metadata.gz: ecccf931f808308fde6ab00654e43fdcbe7b90e0f0c929ade43a25a427302756
+  data.tar.gz: 03af540433b453863a3d399a67565724c68288c0a4a2b283462f613293a4a6a0
 SHA512:
-  metadata.gz: 19e1dfe5f0315b38572c0c8464852bfb7f2c25477f92f646c73df44d4b0c0f06d72c32cd6e961ef8185ed1ced37c57cd111a4980dec8f698d1eba3ad7596e8c7
-  data.tar.gz: 16ff4c84f2f86b690116792e97cfcbe323c5dd2209d63e5148f6d4aa35fc3725a99dc84b87695cb4d00b9187816ab6652f1194ba7940caf11f6d96dd065b4fdf
+  metadata.gz: c999f3855347dda4bfac0ce490ec94666f1e9e2cf00b2907d0ad72fa5c083e00495e0f4296036770d106bb1decddca02a37b495e71d87552344899a4321cba08
+  data.tar.gz: 0decf0ad84220579f16b3606d9c6ee3d6193e0a4dfbee22474cd4ee8008b5a75c6fc4bfc9f77bb8d27ae14fbdf65a3c95c957644ac318e08caffe03f7d0e768c

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-10-08
+
+### Added
+
+- Execute protected draft create/update, ready and merge through named forge providers, binding exact repository provenance, candidate SHA, input and current campaign acceptance.
+
+### Fixed
+
+- Resolve receiver provider identity from the authenticated PR URL and preserve uncertain effects without replay.
+
+- Verify protected request, status and delivery refuse actual authority endpoint loss without replacing the original claim or dispatching another effect.
+
+- Restore process-wide provider registrations and loader state after registry test fixtures, preserving real adapter tests across randomized single-batch execution.
+
+- Resolve receiver-side merge provider identity from the authenticated PR URL when the prepared candidate has no remote, refusing mismatched or changed pinned servers.
+
+- Route protected delivery through original worker merge request, canonical status and exact result consumption while preserving ordinary delivery and unresolved protected PR policy.
+
+
+### Added
+
+- Fixed receiver-side `service merge` validates the claimed candidate/input, uses the selected neutral provider once, and publishes bounded evidence only for a verified exact-head merged outcome.
+
 ## [0.29.0] - 2026-10-05
 
 ### Removed

data/docs/usage.md

@@ -289,6 +289,23 @@ Note: `test/**/*` and `spec/**/*` are NOT excluded by default - test changes are
 
 ## Provider Packages
 
+`ace-git service create`, `service update`, `service ready` and `service merge`
+are fixed protected receiver handlers. It accepts no
+options; the receiver supplies its claimed JSON envelope on stdin and its
+private materialized candidate directory as the working directory. The handler
+checks the exact input digest, executor, candidate and forge provenance, calls
+the selected neutral operation once, and emits the existing bounded evidence
+response only after verifying the exact PR outcome (and merge commit for merge). An unverified or lost
+outcome emits no success and never retries. This command does not authorize a
+operation or replace the protected worker's canonical receipt acceptance.
+Create/update use an exact `{target,delivery,title,body}` input and remain draft;
+ready uses `{target,delivery}`, merge uses `{target,delivery,method}`. Create targets
+the base repository; all other operations target the exact PR URL. The original
+title remains part of the accepted input; the provider owns its draft encoding
+(Forgejo's WIP prefix). Updating a draft preserves that encoding. Each handler
+publishes the fixed `pr-result.txt` evidence only after its observed content,
+identity, head and draft/merge outcome agree.
+
 `ace-git` is forge-neutral. It defines the server registry (`Ace::Git::ServerRegistry`),
 the provider contract (`Ace::Git::Providers::Base`), and normalized evidence types;
 provider packages own all forge CLI behavior:

data/handbook/workflow-instructions/git/pr/create.wf.md

@@ -22,6 +22,40 @@ Use `forge_server` or `forge_default: true`, mutually exclusive. Neither means r
 {"forge_server":"forge-lab","pr_provenance":{"mode":"canonical","head_repository_url":"https://forge.example/team/repo","head_ref":"feature","base_repository_url":"https://forge.example/team/repo","base_ref":"main"}}
 ```
 
+## Protected worker boundary
+
+The steps below are ordinary managed delivery only. An installed protected
+participant uses the configured receiver and the original canonical authority,
+with no caller-local journal or direct-provider fallback.
+
+The authenticated worker may create/update a draft before independent review.
+Save a nonsecret input object with exactly `target`, `delivery`, `title`, `body`;
+`delivery` is the normalized original forge/provenance mapping. `target` has
+`resource` and nullable `artifact_digest`: the selected base repository URL for
+create, the exact recorded PR URL for update. Title/body are bounded UTF-8 text.
+Request the installed receiver with:
+
+```sh
+ace-lab service request --project PROJECT --assignment ID --attempt ATTEMPT \
+  --mapping MAPPING --scope SCOPE --service SERVICE --operation OPERATION \
+  --candidate-head SHA --candidate-generation CANDIDATE-GENERATION \
+  --expected-generation AUTHORITY-GENERATION --authorization AUTHORIZATION \
+  --request-id REQUEST --input INPUT.json
+```
+
+Use `create` or `update` as OPERATION; each requires its own exact scoped grant.
+The receiver runs the fixed `ace-git service create` or `service update` handler.
+A claim acknowledges admission, not PR success. Retain its complete selection
+and observe `ace-lab service status` as described in
+`wfi://handbook/perform-delivery`. Lost replies stay uncertain; status does not
+repeat an effect. Only canonical completion supplies the created PR URL.
+
+For ready, use the same request with OPERATION `ready` and input containing only
+`target` and `delivery`. Ready and merge require executed checks, accepted
+independent review for the current revision and the matching authorization.
+Local report/reference files cannot replace those canonical proofs. Draft
+creation/update does not grant readiness, merge or publication.
+
 ## Steps
 
 1. Read the task and actual committed diff; prepare a concrete title and description explaining behavior and executed validation. Save the description as a local file.

data/handbook/workflow-instructions/git/pr/update.wf.md

@@ -14,6 +14,40 @@ Update the recorded PR description for the current candidate and preserve provid
 
 A managed assignment with a recorded PR and active delivery attempt. Reuse the original forge selection and complete fork/canonical provenance; changed configuration or identity is a conflict. A new committed candidate, including task-only changes, requires renewed tests and independent review.
 
+## Protected worker boundary
+
+The steps below are ordinary managed delivery only. An installed protected
+participant uses the configured receiver and the original canonical authority,
+with no caller-local journal or direct-provider fallback.
+
+The authenticated worker may create/update a draft before independent review.
+Save a nonsecret input object with exactly `target`, `delivery`, `title`, `body`;
+`delivery` is the normalized original forge/provenance mapping. `target` has
+`resource` and nullable `artifact_digest`: the selected base repository URL for
+create, the exact recorded PR URL for update. Title/body are bounded UTF-8 text.
+Request the installed receiver with:
+
+```sh
+ace-lab service request --project PROJECT --assignment ID --attempt ATTEMPT \
+  --mapping MAPPING --scope SCOPE --service SERVICE --operation OPERATION \
+  --candidate-head SHA --candidate-generation CANDIDATE-GENERATION \
+  --expected-generation AUTHORITY-GENERATION --authorization AUTHORIZATION \
+  --request-id REQUEST --input INPUT.json
+```
+
+Use `create` or `update` as OPERATION; each requires its own exact scoped grant.
+The receiver runs the fixed `ace-git service create` or `service update` handler.
+A claim acknowledges admission, not PR success. Retain its complete selection
+and observe `ace-lab service status` as described in
+`wfi://handbook/perform-delivery`. Lost replies stay uncertain; status does not
+repeat an effect. Only canonical completion supplies the created PR URL.
+
+For ready, use the same request with OPERATION `ready` and input containing only
+`target` and `delivery`. Ready and merge require executed checks, accepted
+independent review for the current revision and the matching authorization.
+Local report/reference files cannot replace those canonical proofs. Draft
+creation/update does not grant readiness, merge or publication.
+
 ## Steps
 
 1. Inspect the committed changes and accepted test/review evidence. Prepare the final description with the concrete behavior, executed test results, independent verdict, and actual limitations. Save it as a local file; do not put credentials or terminal dumps in the attempt journal.

data/lib/ace/git/atoms/delivery_parameters.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+require_relative "server_url"
+
+module Ace
+  module Git
+    module Atoms
+      # Explicit non-secret remote delivery inputs; local recipes need not call this validator.
+      module DeliveryParameters
+        PROVENANCE_FIELDS = %w[mode head_repository_url head_ref base_repository_url base_ref].freeze
+        def self.validate(input)
+          raise ArgumentError, "Delivery parameters must be a mapping" unless input.is_a?(Hash)
+          unless (input.keys - %w[forge_server forge_default pr_provenance]).empty?
+            raise ArgumentError, "Unexpected delivery parameter fields"
+          end
+          default = input.fetch("forge_default", false)
+          raise ArgumentError, "forge_default must be boolean" unless [true, false].include?(default)
+          server = input["forge_server"]
+          if server && (!server.is_a?(String) || !server.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/))
+            raise ArgumentError, "Invalid forge_server"
+          end
+          raise ArgumentError, "forge_server and forge_default are mutually exclusive" if server && default
+          provenance = input["pr_provenance"]
+          unless provenance.is_a?(Hash) && provenance.keys.sort == PROVENANCE_FIELDS.sort &&
+              %w[fork canonical].include?(provenance["mode"])
+            raise ArgumentError, "Explicit complete fork or canonical PR provenance is required"
+          end
+          %w[head_repository_url base_repository_url].each { |key| validate_url!(provenance[key]) }
+          %w[head_ref base_ref].each do |key|
+            ref = provenance[key]
+            unless ref.is_a?(String) && ref.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_\/.\-]{0,255}\z/) &&
+                !ref.include?("..") && !ref.include?("//") && !ref.end_with?("/", ".", ".lock")
+              raise ArgumentError, "Invalid PR ref"
+            end
+          end
+          if provenance["mode"] == "canonical" && !Ace::Git::Atoms::ServerUrl.match?(
+              provenance["head_repository_url"], provenance["base_repository_url"])
+            raise ArgumentError, "Canonical provenance requires matching head and base repositories"
+          end
+          {"forge_server" => server, "forge_default" => default,
+           "pr_provenance" => provenance.transform_values(&:dup)}
+        end
+
+        def self.validate_url!(url)
+          unless url.is_a?(String) && url.length <= 512 &&
+              (url.match?(%r{\Ahttps?://[a-zA-Z0-9.:-]+/[a-zA-Z0-9_./-]+\z}) ||
+               url.match?(%r{\Agit@[a-zA-Z0-9.-]+:[a-zA-Z0-9_./-]+\z}) ||
+               url.match?(%r{\Assh://git@[a-zA-Z0-9.:-]+/[a-zA-Z0-9_./-]+\z}))
+            raise ArgumentError, "PR repository URL must contain a repository and no credentials or query"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/atoms/service_merge_evidence.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+require "json"
+require_relative "delivery_parameters"
+require_relative "pr_reference"
+require_relative "../providers/evidence"
+
+module Ace
+  module Git
+    module Atoms
+      # Parse executor-owned evidence; authority supplies the original binding
+      # and separately checks the reconstructed input's canonical digest.
+      module ServiceMergeEvidence
+        MAX_BYTES = 64 * 1024
+        def self.validate(bytes, request_id:, input_digest:, target:, head:)
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, MAX_BYTES) &&
+              bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding? && !bytes.include?("\0")
+            raise ArgumentError, "merge evidence is invalid or oversized"
+          end
+          marker, payload = bytes.split("\n", 2)
+          unless marker == "ace-service-attestation request:#{request_id} input:#{input_digest} outcome:succeeded"
+            raise ArgumentError, "merge evidence original marker differs"
+          end
+          value = JSON.parse(payload.to_s, max_nesting: 16, create_additions: false,
+            allow_duplicate_key: false, allow_comments: false, allow_nan: false)
+          closed!(value, %w[server delivery method candidate_head receipt])
+          delivery = DeliveryParameters.validate(value.fetch("delivery"))
+          unless value["delivery"] == delivery && value["delivery"].keys.sort == %w[forge_default forge_server pr_provenance] &&
+              %w[squash merge rebase].include?(value["method"]) && value["candidate_head"] == head
+            raise ArgumentError, "merge evidence selection/method/head differs"
+          end
+          server, receipt = value.values_at("server", "receipt")
+          closed!(server, %w[name provider url])
+          closed!(receipt, %w[server_name operation pull_request idempotency])
+          unless server["name"].is_a?(String) && server["name"].match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/) &&
+              server["provider"].is_a?(String) && server["provider"].match?(/\A[a-zA-Z0-9_-]{1,128}\z/) &&
+              receipt["server_name"] == server["name"] && receipt["operation"] == "merge"
+            raise ArgumentError, "merge evidence provider receipt differs"
+          end
+          DeliveryParameters.validate_url!(server["url"])
+          pr = receipt.fetch("pull_request")
+          closed!(pr, ProviderPullRequest.members.map(&:to_s))
+          provenance = delivery.fetch("pr_provenance")
+          reference = target.is_a?(Hash) && PrReference.parse(target["resource"])
+          unless reference && reference.repository_url && pr["number"].is_a?(Integer) && pr["number"].positive? &&
+              pr["number"] == reference.number && pr["url"] == target["resource"] && pr["server_name"] == server["name"] &&
+              pr["head_sha"] == head && head.is_a?(String) && head.match?(/\A[0-9a-f]{40}\z/) &&
+              pr["state"] == "merged" && [true, false].include?(pr["draft"]) &&
+              pr.except("number", "draft").values.all? { |value| value.nil? || value.is_a?(String) } &&
+              pr["merge_commit_sha"].is_a?(String) && pr["merge_commit_sha"].match?(/\A[0-9a-f]{40}\z/) &&
+              pr["head_ref"] == provenance["head_ref"] && pr["base_ref"] == provenance["base_ref"] &&
+              ServerUrl.match?(reference.repository_url, provenance["base_repository_url"]) &&
+              ServerUrl.match?(server["url"], provenance["base_repository_url"]) &&
+              ServerUrl.match?(pr["head_repository_url"], provenance["head_repository_url"]) &&
+              ServerUrl.match?(pr["base_repository_url"], provenance["base_repository_url"]) &&
+              (!delivery["forge_server"] || delivery["forge_server"] == server["name"])
+            raise ArgumentError, "merge evidence PR identity or outcome differs"
+          end
+          {input: {"target" => target, "delivery" => delivery, "method" => value.fetch("method")},
+            pr: pr, server: server}
+        rescue JSON::ParserError, KeyError, TypeError
+          raise ArgumentError, "merge evidence is malformed"
+        end
+
+        def self.closed!(value, fields)
+          raise ArgumentError, "merge evidence fields differ" unless value.is_a?(Hash) && value.keys.sort == fields.sort
+        end
+        private_class_method :closed!
+      end
+    end
+  end
+end

data/lib/ace/git/atoms/service_pr_evidence.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+require "json"
+require_relative "service_pr_input"
+require_relative "../providers"
+require_relative "../server_registry"
+
+module Ace
+  module Git
+    module Atoms
+      module ServicePrEvidence
+        def self.validate(bytes, operation:, request_id:, input_digest:, target:, head:)
+          unless ServicePrInput::DRAFT_OPERATIONS.include?(operation) || operation == "ready"
+            raise ArgumentError, "unsupported PR evidence operation"
+          end
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, 64 * 1024) &&
+              bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding? && !bytes.include?("\0")
+            raise ArgumentError, "PR evidence is invalid or oversized"
+          end
+          marker, payload = bytes.split("\n", 2)
+          unless marker == "ace-service-attestation request:#{request_id} input:#{input_digest} outcome:succeeded"
+            raise ArgumentError, "PR evidence original marker differs"
+          end
+          value = JSON.parse(payload.to_s, max_nesting: 16, create_additions: false,
+            allow_duplicate_key: false, allow_comments: false, allow_nan: false)
+          closed!(value, %w[server operation input candidate_head receipt])
+          input = ServicePrInput.validate(value.fetch("input"), operation: operation)
+          unless value["operation"] == operation && value["candidate_head"] == head && input["target"] == target
+            raise ArgumentError, "PR evidence operation/input/head differs"
+          end
+          server, receipt = value.values_at("server", "receipt")
+          closed!(server, %w[name provider url])
+          closed!(receipt, %w[server_name operation pull_request idempotency])
+          pr = receipt.fetch("pull_request")
+          closed!(pr, ProviderPullRequest.members.map(&:to_s))
+          delivery = input.fetch("delivery")
+          provenance = delivery.fetch("pr_provenance")
+          reference = PrReference.parse(pr["url"])
+          unless server["name"].is_a?(String) && server["provider"].is_a?(String) && server["url"].is_a?(String)
+            raise ArgumentError, "PR evidence provider identity is malformed"
+          end
+          selected = ResolvedServer.new(name: server["name"], provider: server["provider"], url: server["url"])
+          expected_title = Providers.for(selected).class.pull_request_title(title: input["title"], draft: true) if ServicePrInput::DRAFT_OPERATIONS.include?(operation)
+          unless reference && reference.repository_url && pr["number"] == reference.number &&
+              pr["number"].is_a?(Integer) && pr["number"].positive? &&
+              server["name"].is_a?(String) && server["name"].match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/) &&
+              server["provider"].is_a?(String) && server["provider"].match?(/\A[a-zA-Z0-9_-]{1,128}\z/) &&
+              receipt["server_name"] == server["name"] && receipt["operation"] == operation &&
+              pr["server_name"] == server["name"] && pr["head_sha"] == head &&
+              head.is_a?(String) && head.match?(/\A[0-9a-f]{40}\z/) && pr["state"] == "open" &&
+              pr["draft"] == ServicePrInput::DRAFT_OPERATIONS.include?(operation) &&
+              pr.except("number", "draft").values.all? { |item| item.nil? || item.is_a?(String) } &&
+              (operation == "create" ? %w[created existing].include?(receipt["idempotency"]) : receipt["idempotency"].nil?) &&
+              pr["head_ref"] == provenance["head_ref"] && pr["base_ref"] == provenance["base_ref"] &&
+              ServerUrl.match?(reference.repository_url, provenance["base_repository_url"]) &&
+              ServerUrl.match?(server["url"], provenance["base_repository_url"]) &&
+              ServerUrl.match?(pr["head_repository_url"], provenance["head_repository_url"]) &&
+              ServerUrl.match?(pr["base_repository_url"], provenance["base_repository_url"]) &&
+              (!delivery["forge_server"] || delivery["forge_server"] == server["name"]) &&
+              (operation == "create" || pr["url"] == target["resource"]) &&
+              (operation == "ready" || pr["title"] == expected_title && pr["body"] == input["body"])
+            raise ArgumentError, "PR evidence selected identity or outcome differs"
+          end
+          DeliveryParameters.validate_url!(server["url"])
+          {input: input, pr: pr, server: server}
+        rescue JSON::ParserError, KeyError, TypeError, Ace::Git::Error
+          raise ArgumentError, "PR evidence is malformed"
+        end
+
+        def self.closed!(value, fields)
+          raise ArgumentError, "PR evidence fields differ" unless value.is_a?(Hash) && value.keys.sort == fields.sort
+        end
+        private_class_method :closed!
+      end
+    end
+  end
+end

data/lib/ace/git/atoms/service_pr_input.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+require_relative "delivery_parameters"
+require_relative "pr_reference"
+
+module Ace
+  module Git
+    module Atoms
+      # Fixed receiver input vocabulary; draft is source policy, not a flag.
+      module ServicePrInput
+        OPERATIONS = %w[create update ready merge].freeze
+        DRAFT_OPERATIONS = %w[create update].freeze
+
+        def self.validate(input, operation:)
+          fields = case operation
+          when "create", "update" then %w[target delivery title body]
+          when "ready" then %w[target delivery]
+          when "merge" then %w[target delivery method]
+          else raise ArgumentError, "unsupported protected PR operation"
+          end
+          unless input.is_a?(Hash) && input.keys.sort == fields.sort &&
+              input["target"].is_a?(Hash) && input["target"].keys.sort == %w[artifact_digest resource]
+            raise ArgumentError, "protected PR input fields differ"
+          end
+          parameters = DeliveryParameters.validate(input.fetch("delivery"))
+          unless input["delivery"].keys.sort == %w[forge_default forge_server pr_provenance] && input["delivery"] == parameters
+            raise ArgumentError, "protected PR selection must be normalized"
+          end
+          resource = input.fetch("target").fetch("resource")
+          if operation == "create"
+            DeliveryParameters.validate_url!(resource)
+            unless ServerUrl.match?(resource, parameters.fetch("pr_provenance").fetch("base_repository_url"))
+              raise ArgumentError, "draft create target differs from base repository"
+            end
+          else
+            reference = resource.is_a?(String) && PrReference.parse(resource)
+            raise ArgumentError, "protected PR target requires an exact URL" unless reference && reference.repository_url
+          end
+          digest = input.fetch("target").fetch("artifact_digest")
+          unless digest.nil? || digest.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(digest)
+            raise ArgumentError, "protected PR target artifact digest differs"
+          end
+          if DRAFT_OPERATIONS.include?(operation)
+            unless input["title"].is_a?(String) && input["title"].bytesize.between?(1, 1024) &&
+                input["body"].is_a?(String) && input["body"].bytesize <= 32 * 1024 &&
+                [input["title"], input["body"]].all? { |text| text.dup.force_encoding(Encoding::UTF_8).valid_encoding? && !text.include?("\0") }
+              raise ArgumentError, "draft PR requires bounded UTF-8 title/body"
+            end
+          elsif operation == "merge" && !%w[squash merge rebase].include?(input["method"])
+            raise ArgumentError, "protected merge requires an exact method"
+          end
+          input
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/cli/commands/service_merge.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+require_relative "../../organisms/service_merge"
+
+module Ace
+  module Git
+    module CLI
+      module Commands
+        class ServiceMerge < Ace::Support::Cli::Command
+          desc "Execute a fixed receiver-owned exact-head PR envelope"
+
+          def initialize(input: nil, producer: nil, root: nil, operation: "merge")
+            @input, @producer, @root, @operation = input, producer, root, operation
+          end
+
+          def call(**options)
+            raise ArgumentError, "fixed PR entry accepts no options" unless options.empty?
+            bytes = (@input || $stdin).read(Organisms::ServiceMerge::MAX_INPUT + 1)
+            result = (@producer || Organisms::ServiceMerge.new(operation: @operation)).call(bytes: bytes, root: @root || Dir.pwd)
+            puts JSON.generate(result)
+          rescue Ace::Git::Error, ArgumentError, SystemCallError, IOError => error
+            # No stdout receipt on an unverified/uncertain effect. The existing
+            # receiver retains its original dispatch instead of retrying it.
+            raise Ace::Support::Cli::Error, error.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/cli.rb

@@ -7,6 +7,7 @@ require_relative "cli/commands/diff"
 require_relative "cli/commands/status"
 require_relative "cli/commands/branch"
 require_relative "cli/commands/pr"
+require_relative "cli/commands/service_merge"
 
 module Ace
   module Git
@@ -52,7 +53,11 @@ module Ace
         ["diff", "Show filtered git diff output"],
         ["status", "Show repository status and PR context"],
         ["branch", "Show current branch information"],
-        ["pr", "Forge-neutral pull request lifecycle: show, create, update, ready, merge"]
+        ["pr", "Forge-neutral pull request lifecycle: show, create, update, ready, merge"],
+        ["service merge", "Fixed receiver-owned exact-head merge envelope"],
+        ["service create", "Fixed receiver-owned draft PR creation"],
+        ["service update", "Fixed receiver-owned draft PR update"],
+        ["service ready", "Fixed receiver-owned reviewed PR readiness"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -70,6 +75,10 @@ module Ace
       register "pr update", Commands::Pr::Update.new
       register "pr ready", Commands::Pr::Ready.new
       register "pr merge", Commands::Pr::Merge.new
+      register "service merge", Commands::ServiceMerge.new
+      %w[create update ready].each do |operation|
+        register "service #{operation}", Commands::ServiceMerge.new(operation: operation)
+      end
 
       version_cmd = Ace::Support::Cli::VersionCommand.build(
         gem_name: "ace-git",

data/lib/ace/git/organisms/pull_request_lifecycle.rb

@@ -196,6 +196,11 @@ module Ace
           )
         end
 
+        # Pure provider-owned encoding; selection is pinned by the caller.
+        def draft_title(title)
+          provider_for(resolve_selected_server).class.pull_request_title(title: title, draft: true)
+        end
+
         # Update title/body after exact-head verification.
         #
         # @return [ProviderMutationReceipt]
@@ -237,8 +242,23 @@ module Ace
         end
 
         # Freeze the selected provider identity for an assignment attempt.
-        def resolved_identity
-          resolve_selected_server.to_h.transform_keys(&:to_s).transform_values(&:to_s)
+        def resolved_identity(identifier = nil)
+          selected = identifier.nil? ? resolve_selected_server : resolve_server_for(parse_identifier(identifier))
+          if @pinned_server && selected != @pinned_server
+            raise ProviderIdentityMismatchError, "Configured server identity changed from the pinned delivery identity"
+          end
+          selected.to_h.transform_keys(&:to_s).transform_values(&:to_s)
+        end
+
+        # Protected create has no PR identifier or materialized origin remote.
+        # Resolve the retained base repository through the same exact registry.
+        def resolved_repository_identity(repository_url)
+          Atoms::DeliveryParameters.validate_url!(repository_url)
+          selected = resolve_matching_server(ServerRegistry.matching_servers(repository_url), repository_url)
+          if @pinned_server && selected != @pinned_server
+            raise ProviderIdentityMismatchError, "Configured server identity changed from the pinned delivery identity"
+          end
+          selected.to_h.transform_keys(&:to_s).transform_values(&:to_s)
         end
 
         # Read-only reconciliation of a possibly completed create. Absence
@@ -291,10 +311,13 @@ module Ace
             ServerRegistry.servers_for_owner_repo(reference.owner_repo)
           end
 
+          resolve_matching_server(candidates, reference.repository_url || reference.owner_repo)
+        end
+
+        def resolve_matching_server(candidates, identity)
           if @selection[:server_name] || @selection[:use_default]
             selected = resolve_selected_server
             unless candidates.any? { |candidate| candidate.name == selected.name }
-              identity = reference.repository_url || reference.owner_repo
               raise ProviderIdentityMismatchError,
                 "PR identifier (#{identity}) does not match the selected server '#{selected.name}'"
             end
@@ -303,12 +326,10 @@ module Ace
           elsif candidates.size == 1
             candidates.first
           elsif candidates.empty?
-            identity = reference.repository_url || reference.owner_repo
             raise AmbiguousRemoteError,
               "PR repository '#{identity}' matches no configured server (configured: " \
               "#{ServerRegistry.servers.map(&:name).join(", ")})"
           else
-            identity = reference.repository_url || reference.owner_repo
             raise AmbiguousRemoteError,
               "PR repository '#{identity}' matches multiple configured servers " \
               "(#{candidates.map(&:name).join(", ")}); select one explicitly"

data/lib/ace/git/organisms/service_merge.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+require "json"
+require "digest"
+require_relative "pull_request_lifecycle"
+require_relative "../atoms/delivery_parameters"
+require_relative "../atoms/service_pr_input"
+
+module Ace
+  module Git
+    module Organisms
+      # A fixed receiver-side operation, never a grant or a worker fallback.
+      class ServiceMerge
+        MAX_INPUT = 128 * 1024
+        MAX_SERVICE_INPUT = 64 * 1024
+        MAX_ARTIFACT = 64 * 1024
+        ARTIFACT = "pr-result.txt"
+        REQUEST = %w[request_id assignment_id attempt_id project_id operation input_digest target candidate_head
+          executor_uid transport authorization service_id caller_uid].freeze
+        EXECUTION = %w[executor_uid authority_id claim_binding candidate_generation head staging_id].freeze
+        TOKEN = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/
+        SHA = /\A[0-9a-f]{40}\z/
+        DIGEST = /\A[0-9a-f]{64}\z/
+
+        def initialize(operation: "merge", lifecycle_factory: nil, uid: -> { Process.uid }, euid: -> { Process.euid })
+          raise ArgumentError, "unsupported fixed PR operation" unless Atoms::ServicePrInput::OPERATIONS.include?(operation)
+          @operation = operation
+          @factory = lifecycle_factory || ->(**selection) { PullRequestLifecycle.new(**selection) }
+          @uid, @euid = uid, euid
+        end
+
+        def call(bytes:, root:)
+          envelope = parse!(bytes)
+          request, execution, input = envelope.values_at("request", "execution", "input")
+          parameters = Atoms::DeliveryParameters.validate(input.fetch("delivery"))
+          Atoms::ServicePrInput.validate(input, operation: @operation)
+          directory, held = private_root!(root)
+          begin
+            lifecycle = @factory.call(server_name: parameters["forge_server"], use_default: parameters.fetch("forge_default"), repo_root: directory)
+            server = if @operation == "create"
+              lifecycle.resolved_repository_identity(request.fetch("target").fetch("resource"))
+            else
+              lifecycle.resolved_identity(request.fetch("target").fetch("resource"))
+            end
+            provenance = parameters.fetch("pr_provenance")
+            unless Atoms::ServerUrl.match?(server.fetch("url"), provenance.fetch("base_repository_url"))
+              raise ProviderIdentityMismatchError, "merge forge differs from accepted provenance"
+            end
+            pinned = ResolvedServer.new(name: server.fetch("name"), provider: server.fetch("provider").to_sym, url: server.fetch("url"))
+            lifecycle = @factory.call(server_name: pinned.name, use_default: false, repo_root: directory, resolved_server: pinned)
+            resource, head = request.fetch("target").fetch("resource"), execution.fetch("head")
+            if @operation != "create"
+              before = lifecycle.show(resource)
+              verify_pr!(before, resource, head, server, provenance)
+              if %w[update ready].include?(@operation) && before.state.to_s != "open"
+                raise ProviderExpectedHeadConflictError, "protected PR edit requires an open PR"
+              end
+              if @operation == "update" && !before.draft
+                raise ProviderExpectedHeadConflictError, "protected update requires a draft PR"
+              end
+            end
+            title = lifecycle.draft_title(input.fetch("title")) if Atoms::ServicePrInput::DRAFT_OPERATIONS.include?(@operation)
+            receipt = case @operation
+            when "create"
+              lifecycle.create(head_ref: provenance.fetch("head_ref"), base_ref: provenance.fetch("base_ref"),
+                head_repository_url: provenance.fetch("head_repository_url"), expected_head: head,
+                title: title, body: input.fetch("body"), draft: true)
+            when "update"
+              lifecycle.update(resource, expected_head: head, title: title, body: input.fetch("body"))
+            when "ready" then lifecycle.ready(resource, expected_head: head)
+            when "merge" then lifecycle.merge(resource, expected_head: head, method: input.fetch("method"))
+            end
+            unless receipt.is_a?(ProviderMutationReceipt) && receipt.server_name == pinned.name && receipt.operation.to_s == @operation
+              raise ProviderUnknownOutcomeError, "PR response does not identify the selected operation"
+            end
+            after = receipt.pull_request
+            raise ProviderUnknownOutcomeError, "PR response lacks its exact result" unless after.is_a?(ProviderPullRequest)
+            verify_pr!(after, @operation == "create" ? after.url : resource, head, server, provenance)
+            if @operation == "merge"
+              unless after.state.to_s == "merged" && after.merge_commit_sha.is_a?(String) && after.merge_commit_sha.match?(SHA)
+                raise ProviderUnknownOutcomeError, "merge outcome is not verified"
+              end
+              payload = {"server" => server, "delivery" => parameters, "method" => input.fetch("method"),
+                "candidate_head" => head, "receipt" => receipt.to_h}
+            else
+              expected_draft = Atoms::ServicePrInput::DRAFT_OPERATIONS.include?(@operation)
+              unless after.state.to_s == "open" && after.draft == expected_draft &&
+                  (!expected_draft || after.title == title && after.body == input.fetch("body"))
+                raise ProviderUnknownOutcomeError, "PR draft/content outcome is not verified"
+              end
+              payload = {"server" => server, "operation" => @operation, "input" => input,
+                "candidate_head" => head, "receipt" => receipt.to_h}
+            end
+            artifact = "ace-service-attestation request:#{request.fetch('request_id')} input:#{request.fetch('input_digest')} outcome:succeeded\n" + JSON.generate(payload) + "\n"
+            digest = publish!(directory, held, artifact)
+            {"request_id" => request.fetch("request_id"), "input_digest" => request.fetch("input_digest"),
+              "outcome" => "succeeded", "evidence" => [{"ref" => ARTIFACT, "sha256" => digest}]}
+          ensure
+            held.close
+          end
+        end
+
+        private
+
+        def parse!(bytes)
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, MAX_INPUT) && bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding? && !bytes.include?("\0")
+            raise ArgumentError, "merge envelope is invalid or oversized"
+          end
+          envelope = JSON.parse(bytes, max_nesting: 16, create_additions: false,
+            allow_duplicate_key: false, allow_comments: false, allow_nan: false)
+          closed!(envelope, %w[version request input execution])
+          raise ArgumentError, "merge envelope version differs" unless envelope["version"].is_a?(Integer) && envelope["version"] == 1
+          request, execution, input = envelope.values_at("request", "execution", "input")
+          closed!(request, REQUEST)
+          closed!(execution, EXECUTION)
+          Atoms::ServicePrInput.validate(input, operation: @operation)
+          raise ArgumentError, "merge service input exceeds receiver bound" if JSON.generate(input).bytesize > MAX_SERVICE_INPUT
+          closed!(input["target"], %w[resource artifact_digest])
+          closed!(request["target"], %w[resource artifact_digest])
+          %w[request_id assignment_id attempt_id project_id authorization service_id].each do |key|
+            raise ArgumentError, "merge request identifier differs" unless request[key].is_a?(String) && request[key].match?(TOKEN)
+          end
+          %w[authority_id staging_id].each do |key|
+            raise ArgumentError, "merge execution identifier differs" unless execution[key].is_a?(String) && execution[key].match?(TOKEN)
+          end
+          unless request["operation"] == @operation && request["transport"] == "unix" &&
+              %w[executor_uid caller_uid].all? { |key| request[key].is_a?(Integer) && request[key].positive? } &&
+              request["executor_uid"] != request["caller_uid"] && request["executor_uid"] == execution["executor_uid"] &&
+              execution["executor_uid"].is_a?(Integer) &&
+              request["executor_uid"] == @uid.call && request["executor_uid"] == @euid.call &&
+              execution["candidate_generation"].is_a?(Integer) && execution["candidate_generation"].positive? &&
+              execution["head"].is_a?(String) && execution["head"].match?(SHA) && request["candidate_head"] == execution["head"] &&
+              execution["claim_binding"].is_a?(String) && execution["claim_binding"].match?(DIGEST) &&
+              request["input_digest"].is_a?(String) && request["input_digest"].match?(DIGEST) &&
+              request["input_digest"] == Digest::SHA256.hexdigest(JSON.generate(canonical(input))) && request["target"] == input["target"]
+            raise ArgumentError, "merge original claim/input/executor join differs"
+          end
+          target = input.fetch("target")
+          reference = target["resource"].is_a?(String) && Atoms::PrReference.parse(target["resource"])
+          unless (@operation == "create" || reference && reference.repository_url) && target["resource"].is_a?(String) && target["resource"].bytesize.between?(1, 256) &&
+              (target["artifact_digest"].nil? || target["artifact_digest"].is_a?(String) && target["artifact_digest"].match?(DIGEST))
+            raise ArgumentError, "merge target requires an exact PR URL"
+          end
+          envelope
+        rescue JSON::ParserError, JSON::NestingError, KeyError
+          raise ArgumentError, "merge envelope is malformed"
+        end
+
+        def closed!(value, fields)
+          raise ArgumentError, "merge fields differ" unless value.is_a?(Hash) && value.keys.sort == fields.sort
+        end
+
+        def canonical(value)
+          case value
+          when Hash then value.keys.sort.to_h { |key| [key, canonical(value.fetch(key))] }
+          when Array then value.map { |item| canonical(item) }
+          else value
+          end
+        end
+
+        def verify_pr!(pr, resource, head, server, provenance)
+          reference = Atoms::PrReference.parse(resource)
+          unless pr.is_a?(ProviderPullRequest) && reference && reference.repository_url && pr.url == resource && pr.number == reference.number &&
+              pr.server_name == server.fetch("name") && pr.head_sha == head &&
+              pr.head_ref == provenance.fetch("head_ref") && pr.base_ref == provenance.fetch("base_ref") &&
+              Atoms::ServerUrl.match?(reference.repository_url, provenance.fetch("base_repository_url")) &&
+              Atoms::ServerUrl.match?(pr.head_repository_url, provenance.fetch("head_repository_url")) &&
+              Atoms::ServerUrl.match?(pr.base_repository_url, provenance.fetch("base_repository_url"))
+            raise ProviderExpectedHeadConflictError, "merge PR identity/head/provenance differs"
+          end
+        end
+
+        def private_root!(root)
+          raise ArgumentError, "merge staging root must be absolute" unless root.is_a?(String) && root.start_with?("/")
+          held = File.open(root, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+          stat = held.stat
+          unless stat.directory? && stat.uid == @uid.call && (stat.mode & 0o7777) == 0o700 &&
+              [stat.dev, stat.ino] == File.lstat(root).then { |value| [value.dev, value.ino] }
+            raise ArgumentError, "merge staging root is not private"
+          end
+          [root, held]
+        rescue StandardError
+          held&.close
+          raise
+        end
+
+        def publish!(root, held, bytes)
+          raise ProviderUnknownOutcomeError, "merge result exceeds evidence bound" unless bytes.bytesize <= MAX_ARTIFACT
+          stat = held.stat
+          identity = [stat.dev, stat.ino]
+          unless stat.directory? && stat.uid == @uid.call && (stat.mode & 0o7777) == 0o700 &&
+              identity == File.lstat(root).then { |value| [value.dev, value.ino] }
+            raise ProviderUnknownOutcomeError, "merge staging root changed"
+          end
+          File.open(File.join(root, ARTIFACT), File::RDWR | File::CREAT | File::EXCL | File::NOFOLLOW | File::NONBLOCK, 0o600) do |file|
+            file.write(bytes); file.flush; file.fsync; file.chmod(0o400)
+            before = file.stat
+            file.rewind
+            captured = file.read(MAX_ARTIFACT + 1)
+            after = file.stat
+            unless before.file? && before.uid == @uid.call && captured == bytes &&
+                [before.dev, before.ino, before.size, before.mtime, before.ctime] == [after.dev, after.ino, after.size, after.mtime, after.ctime]
+              raise ProviderUnknownOutcomeError, "merge held evidence changed"
+            end
+            held.fsync
+            raise ProviderUnknownOutcomeError, "merge staging root changed" unless identity == File.lstat(root).then { |value| [value.dev, value.ino] }
+            Digest::SHA256.hexdigest(captured)
+          end
+        rescue SystemCallError, IOError
+          raise ProviderUnknownOutcomeError, "merge evidence publication unavailable"
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/providers/base.rb

@@ -17,6 +17,12 @@ module Ace
       #   keyword arguments (args:, timeout:, env:) and returning a Hash with
       #   :stdout, :stderr, :exit_code
       class Base
+        # Pure transport title for the requested draft state. Providers own
+        # server-specific draft encodings; callers retain their original title.
+        def self.pull_request_title(title:, draft:)
+          title
+        end
+
         attr_reader :server, :timeout
 
         # @param server [ResolvedServer] resolved server identity

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = "0.29.0"
+    VERSION = "0.30.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -141,6 +141,7 @@ files:
 - lib/ace/git.rb
 - lib/ace/git/atoms/command_executor.rb
 - lib/ace/git/atoms/date_resolver.rb
+- lib/ace/git/atoms/delivery_parameters.rb
 - lib/ace/git/atoms/diff_numstat_parser.rb
 - lib/ace/git/atoms/diff_parser.rb
 - lib/ace/git/atoms/file_grouper.rb
@@ -154,6 +155,9 @@ files:
 - lib/ace/git/atoms/repository_checker.rb
 - lib/ace/git/atoms/repository_state_detector.rb
 - lib/ace/git/atoms/server_url.rb
+- lib/ace/git/atoms/service_merge_evidence.rb
+- lib/ace/git/atoms/service_pr_evidence.rb
+- lib/ace/git/atoms/service_pr_input.rb
 - lib/ace/git/atoms/stale_lock_cleaner.rb
 - lib/ace/git/atoms/status_formatter.rb
 - lib/ace/git/atoms/task_pattern_extractor.rb
@@ -162,6 +166,7 @@ files:
 - lib/ace/git/cli/commands/branch.rb
 - lib/ace/git/cli/commands/diff.rb
 - lib/ace/git/cli/commands/pr.rb
+- lib/ace/git/cli/commands/service_merge.rb
 - lib/ace/git/cli/commands/status.rb
 - lib/ace/git/errors.rb
 - lib/ace/git/models/diff_config.rb
@@ -177,6 +182,7 @@ files:
 - lib/ace/git/organisms/issue_tracking.rb
 - lib/ace/git/organisms/pull_request_lifecycle.rb
 - lib/ace/git/organisms/repo_status_loader.rb
+- lib/ace/git/organisms/service_merge.rb
 - lib/ace/git/providers.rb
 - lib/ace/git/providers/base.rb
 - lib/ace/git/providers/evidence.rb