ace-lab 0.5.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc5e4fcb4d6a771437705ab78e363747cd97d78ce6d32c6a2771b4ef4343af74
-  data.tar.gz: 22de06526b637c15a791944e4594ea94f309e57241ccdc51ae1cd91bbfc98914
+  metadata.gz: d3799161a4575055b78e316deb18a4fa952fb1d84fa9fb10cd6e5c081a36acee
+  data.tar.gz: dd2d0fa5764e5bce423396e93e4fd1751fddd880649219d6a130306d0ec49667
 SHA512:
-  metadata.gz: 599fc84b935b3632918f7ab8546ee4f0d7dd59fb8ea0f7933e660176403d19508e468b9153873a132beec1eb89eecbff0341339b01f9da0629f16a94c3300e93
-  data.tar.gz: cd1758fafa5b8c944fd8b0de736b0d8137ed2b4522ffe067c8bbcad5a5be817e6176fd5a571d6410fc144cf03d88bccbb91d5c7872e9b6c8b29f85066f3c4c81
+  metadata.gz: 1556efc67f0fa45a412b40430570355578c7e61000bda7af07982345631f023c3f56c709d2d02a25c3faf84495b510d6fb171a904d8f910e7c336b4b8113cd44
+  data.tar.gz: a78076debb811ce94046ff8cb056648b6455f8dbe30514a5d575ac417bcf98adce21bb42c3f6f712f0d0e2d6d4bbb3c67ba3764dfb9e4138cb6eb17e6dd6a113

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-16
+
+### Added
+
+- Run the ordinary merge listener and receiver through `service listen`, with authenticated admission, canonical Assign acknowledgement/status/receipts, restart reconciliation and bounded fixed execution.
+- Invoke and inspect real Forgejo merges under the installed scoped service identity; revalidate authorization per request and bind the provider mutation to the approved candidate head.
+
+### Changed
+
+- Require ace-assign 0.69 and ace-git-forgejo 0.7 for the receiver record-listing and scoped provider APIs.
+
+- Move the Forgejo merge provider ownership out of ace-lab (xz9.5): `ForgejoMergeAdapter` is now a thin delegation to the `ace-git-forgejo` provider (`Ace::Git::Forgejo::PullRequestApi` over its `HttpClient`, under the host-installed scoped service identity) — HTTP transport, authentication, payload shape, and failure classification live in the provider package, while the adapter keeps the receiver's closed outcome translation (`:invoked`/`:refused`/`:ambiguous`/`Unavailable`), the exact-head binding guard, and the normalized readback/nil-absence contract unchanged.
+
+## [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,13 @@
 
 require "json"
 require "ace/support/cli"
+require "ace/assign"
 require_relative "support"
 require_relative "../../organisms/protected_service_request"
+require_relative "../../organisms/ordinary_merge_request"
+require_relative "../../organisms/ordinary_merge_receiver"
+require_relative "../../molecules/ordinary_listener"
+require_relative "../../molecules/ordinary_receiver_config"
 
 module Ace
   module Lab
@@ -20,7 +25,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 +54,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 +66,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 +95,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 +120,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 +137,117 @@ 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
+
+          # The ordinary receiver serve entrypoint (spec 8x3.t.xz9.4
+          # execution clauses; 8x3.t.xz9.5 integration handoff): binds the
+          # configured unix socket, mutually authenticates every connection
+          # through SO_PEERCRED, admits through the canonical Assign
+          # coordinator, executes the authorized fixed operation — one REAL
+          # Forgejo merge under the scoped host-installed service identity —
+          # and settles the exact terminal receipt proven by real forge
+          # readback. Configuration is one explicit deployment-owned file
+          # plus the host-installed authorization and forge-merge documents;
+          # the host owns their placement and credentials. Blocks until
+          # stopped.
+          class Listen < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+            include Output
+
+            desc "Serve the ordinary fixed merge receiver on its configured socket"
+            option :mode, type: :string, required: true,
+              desc: "ordinary-merge selects the ordinary fixed merge receiver"
+            option :project, type: :string, required: true, desc: "Project stable ID"
+            option :config, type: :string, required: true,
+              desc: "Deployment-owned receiver configuration file (YAML)"
+
+            def call(mode:, project:, config:, **options)
+              unless options.empty?
+                return emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                  "ordinary_merge_invalid_request",
+                  "unknown listen selector: #{options.keys.sort.join(", ")}",
+                  request_id: "unknown", input_digest: nil
+                ))
+              end
+              unless mode == Organisms::OrdinaryMergeRequest::MODE
+                return emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                  "ordinary_merge_invalid_request", "unknown service mode",
+                  request_id: "unknown", input_digest: nil
+                ))
+              end
+              receiver_config = Molecules::OrdinaryReceiverConfig.load(config)
+              unless receiver_config.project == project
+                return emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                  "ordinary_merge_selection_mismatch",
+                  "configured project does not match the requested project",
+                  request_id: "unknown", input_digest: nil
+                ))
+              end
+              policy_document = Molecules::GrantResolver.trusted_document(
+                receiver_config.policy_path
+              )
+              # The ONE canonical Assign journal: the coordinator binds the
+              # evidence ref of the canonical repository the receiver is
+              # installed for (config repo_path — the producer project's
+              # canonical checkout, the same authoritative journal the
+              # producer coordinator uses). Never an integration-checkout
+              # duplicate; the service identity's reviewed permissions are
+              # journal ref read/append, evidence checkout and no-effect
+              # attestation writes inside that repository.
+              coordinator = Ace::Assign::Organisms::AttemptCoordinator.new(
+                repo_root: receiver_config.repo_path
+              )
+              receiver = Organisms::OrdinaryMergeReceiver.new(
+                config: receiver_config, coordinator: coordinator,
+                policy_document: policy_document
+              )
+              listener = Molecules::OrdinaryListener.new(
+                socket_path: receiver_config.socket_path,
+                peer_uid: receiver_config.principal_uid,
+                handler: receiver
+              )
+              receiver.recover_pending!
+              listener.serve
+            rescue Ace::Lab::InvalidConfigurationError, Ace::Assign::AttemptErrors::EvidenceUnavailable => e
+              emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                "ordinary_merge_unavailable", e.message,
+                request_id: "unknown", input_digest: nil
+              ))
+            end
           end
         end
       end

data/lib/ace/lab/cli.rb

@@ -26,7 +26,8 @@ module Ace
         ["resolve", "Resolve one lab entry by exact stable ID"],
         ["route", "Select a configured capable service in a project"],
         ["service request", "Request one authorized service operation"],
-        ["service status", "Read a service request outcome"]
+        ["service status", "Read a service request outcome"],
+        ["service listen", "Serve the ordinary fixed merge receiver on its configured socket"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -52,6 +53,7 @@ module Ace
       register "route", CLI::Commands::Route.new
       register "service request", CLI::Commands::Service::Request.new
       register "service status", CLI::Commands::Service::Status.new
+      register "service listen", CLI::Commands::Service::Listen.new
 
       # Register version command
       version_cmd = Ace::Support::Cli::VersionCommand.build(

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../errors"
+require_relative "grant_resolver"
+
+module Ace
+  module Lab
+    module Molecules
+      # The host-installed forge merge configuration for the ordinary merge
+      # receiver (spec 8x3.t.xz9.5 integration handoff). The scoped service
+      # identity that may merge pull requests is provisioned by the HOST in
+      # one root-owned file at a fixed path; this loader reads it through the
+      # same trusted-storage verification as the authorization grants and
+      # fails closed on anything else. An absent file is an immediate
+      # actionable refusal naming the path and its owner — never a silent
+      # local fallback and never an invented credential: a receiver without
+      # the host-installed identity cannot merge and must say so.
+      #
+      # Contract (host installs, root-owned 0640, service-readable):
+      #
+      #   base_url: https://forgejo.example.net
+      #   owner: cs3b
+      #   repo: ace
+      #   token: <scoped: PR read + PR merge + PR comment on that repo only>
+      #   merge_timeout_seconds: 900
+      #   escalation_owner: host-integrator
+      #   review_attachment:
+      #     enabled: true
+      class ForgeMergeConfig
+        DEFAULT_PATH = "/etc/lab/ace-lab/forge-merge.yml"
+        DEFAULT_ESCALATION_OWNER = "host-integrator"
+        KEYS = %w[base_url owner repo token merge_timeout_seconds escalation_owner
+          review_attachment].freeze
+
+        # @raise [Ace::Lab::InvalidConfigurationError] absent file ⇒ the
+        #   actionable `config missing:` message naming the path and owner;
+        #   every other trust/shape failure also fails closed.
+        def self.load(path = DEFAULT_PATH)
+          content = GrantResolver.read_verified(path)
+          unless content
+            raise Ace::Lab::InvalidConfigurationError,
+              "config missing: #{path} (owner: #{DEFAULT_ESCALATION_OWNER} — install the " \
+              "root-owned 0640 forge merge configuration for the scoped service identity)"
+          end
+          document = YAML.safe_load(content, permitted_classes: [Date], aliases: false)
+          new(document, source: path)
+        rescue Psych::Exception
+          raise Ace::Lab::InvalidConfigurationError,
+            "invalid lab configuration: forge merge configuration #{path} could not be parsed"
+        end
+
+        attr_reader :base_url, :owner, :repo, :token, :merge_timeout_seconds, :escalation_owner,
+          :review_attachment_enabled, :source
+
+        def initialize(document, source: nil)
+          unless document.is_a?(Hash) && (document.keys - KEYS).empty? &&
+              (KEYS - document.keys).empty?
+            raise Ace::Lab::InvalidConfigurationError,
+              "forge merge configuration must contain exactly: #{KEYS.join(", ")}"
+          end
+          @source = source
+          @base_url = base_url!(document.fetch("base_url"))
+          @owner = name!(document.fetch("owner"), "owner")
+          @repo = name!(document.fetch("repo"), "repo")
+          @token = token!(document.fetch("token"))
+          @merge_timeout_seconds = timeout!(document.fetch("merge_timeout_seconds"))
+          @escalation_owner = name!(document.fetch("escalation_owner"), "escalation_owner")
+          attachment = document.fetch("review_attachment")
+          unless attachment.is_a?(Hash) && attachment.keys == %w[enabled] &&
+              [true, false].include?(attachment.fetch("enabled"))
+            raise Ace::Lab::InvalidConfigurationError,
+              "forge merge review_attachment must be exactly {enabled: true|false}"
+          end
+          @review_attachment_enabled = attachment.fetch("enabled")
+          freeze
+        end
+
+        # The token is a live credential: never rendered, never logged.
+        def inspect
+          "#<#{self.class.name} base_url=#{@base_url} owner=#{@owner} repo=#{@repo} " \
+            "token=[REDACTED] merge_timeout_seconds=#{@merge_timeout_seconds} " \
+            "escalation_owner=#{@escalation_owner} " \
+            "review_attachment_enabled=#{@review_attachment_enabled}>"
+        end
+
+        private
+
+        def base_url!(value)
+          uri = URI.parse(value.to_s)
+          unless uri.is_a?(URI::HTTPS) && uri.host && uri.path.empty? && uri.to_s == value
+            raise Ace::Lab::InvalidConfigurationError,
+              "forge merge base_url must be an https origin without path, query or fragment"
+          end
+          value
+        rescue URI::Error
+          raise Ace::Lab::InvalidConfigurationError,
+            "forge merge base_url must be an https origin without path, query or fragment"
+        end
+
+        def name!(value, name)
+          unless value.is_a?(String) && !value.empty? && value.length <= 256 &&
+              value.match?(%r{\A[A-Za-z0-9._-]+\z})
+            raise Ace::Lab::InvalidConfigurationError, "forge merge #{name} is invalid"
+          end
+          value
+        end
+
+        def token!(value)
+          unless value.is_a?(String) && value.length.between?(8, 512) &&
+              value.match?(%r{\A[A-Za-z0-9._~+/=-]+\z})
+            raise Ace::Lab::InvalidConfigurationError, "forge merge token is invalid"
+          end
+          value
+        end
+
+        def timeout!(value)
+          unless value.is_a?(Integer) && value.positive? && value <= 86_400
+            raise Ace::Lab::InvalidConfigurationError,
+              "forge merge merge_timeout_seconds must be a positive integer"
+          end
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "ace/git/forgejo"
+
+module Ace
+  module Lab
+    module Molecules
+      # The receiver's forge merge boundary (spec 8x3.t.xz9.5 integration
+      # handoff): a THIN delegation to the `ace-git-forgejo` provider, which
+      # owns every Forgejo API/PR/review/merge/readback responsibility —
+      # HTTP transport, authentication, payload shape, and failure
+      # classification live behind `Ace::Git::Forgejo::PullRequestApi` and
+      # its `HttpClient`. This molecule holds no HTTP stack of its own: it
+      # binds the host-installed scoped service identity from
+      # {ForgeMergeConfig} to a repository-scoped provider client and
+      # translates the provider's closed outcomes into the receiver's
+      # closed outcome set (`:invoked`/`:refused`/`:ambiguous`/`Unavailable`).
+      #
+      # The receiver's one authorized effect is a real pull request merge on
+      # the real forge, invoked under the scoped service identity, and every
+      # terminal outcome is proven by a real readback — a local git effect is
+      # never presented as a forge result.
+      #
+      # Outcome translation (provider closed world → receiver closed world):
+      #
+      # - `2xx` mutation outcome → `:invoked`; a provider refusal outcome
+      #   (404/405/409/422 — including the server-side exact-head refusal
+      #   for a moved head) → `:refused`; an authentication error (the
+      #   provider raises the shared taxonomy for 401/403) → `:refused` —
+      #   a definitive refusal can never have merged.
+      # - An unknown mutation outcome (5xx responses and transport failures
+      #   on the POST — the forge may or may not have processed it) →
+      #   `:ambiguous`; the receiver reconciles by readback, never by
+      #   repeating the merge.
+      # - Every unverifiable read outcome (unreachable forge, malformed
+      #   evidence, misrouted payload, unusable endpoint) raises
+      #   `Unavailable`, because the true state cannot be proven. The token
+      #   is never rendered in any error (provider-sanitized messages only).
+      #
+      # The exact-head contract is carried by the provider's native merge
+      # signature: the POST body binds `head_commit_id` to the approved
+      # candidate server-side, so a race between the state readback and the
+      # merge POST can never merge an unreviewed head. This molecule never
+      # substitutes another merge strategy and validates the binding before
+      # the provider is constructed.
+      class ForgejoMergeAdapter
+        # The single authorized merge strategy on the wire.
+        MERGE_METHOD = "fast-forward-only"
+
+        class Unavailable < ::StandardError; end
+
+        # outcome: :invoked | :refused | :ambiguous; status: Integer|nil;
+        # reason: closed refuse/ambiguity detail (token-free).
+        Result = Struct.new(:outcome, :status, :reason, keyword_init: true)
+
+        def initialize(base_url:, token:, timeout_seconds: 900)
+          @base_url = base_url.to_s.sub(%r{/+\z}, "")
+          @token = token
+          @timeout_seconds = timeout_seconds
+          freeze
+        end
+
+        # Invoke the eligible merge bound to the approved candidate head.
+        # `head_commit_id` is required and validated (full 40-character hex
+        # sha) BEFORE any provider construction: the forge server-side
+        # refuses to merge any head other than the bound one. Returns a
+        # Result; never raises for HTTP outcomes (ambiguity is a result, not
+        # an exception).
+        def merge_pull_request!(owner:, repo:, index:, head_commit_id:)
+          unless head_commit_id.is_a?(String) && head_commit_id.match?(/\A[0-9a-f]{40}\z/)
+            raise ArgumentError,
+              "head_commit_id must be a full 40-character lowercase hex sha " \
+                "(got: #{head_commit_id.inspect})"
+          end
+          translate_mutation do
+            provider(owner, repo).merge_pull_request(index,
+              do_method: MERGE_METHOD, head_commit_id: head_commit_id)
+          end
+        end
+
+        # The PR state readback, normalized to the receiver's closed
+        # PR-state shape (`merged`, `merge_commit_sha`, head/base shas) or
+        # nil when the forge definitively reports the PR absent (404 — the
+        # provider raises the absence taxonomy). Raises Unavailable for
+        # every unverifiable outcome.
+        def pull_request(owner:, repo:, index:)
+          payload = provider(owner, repo).pull_request(index)
+          {
+            "merged" => payload["merged"] == true,
+            "merge_commit_sha" => payload["merge_commit_sha"].is_a?(String) ?
+              payload["merge_commit_sha"] : nil,
+            "head" => {"sha" => payload.dig("head", "sha").is_a?(String) ?
+              payload.dig("head", "sha") : nil},
+            "base" => {"sha" => payload.dig("base", "sha").is_a?(String) ?
+              payload.dig("base", "sha") : nil}
+          }
+        rescue Ace::Git::ProviderObjectNotFoundError
+          nil
+        rescue Ace::Git::Error => e
+          raise Unavailable, e.message
+        end
+
+        # Attach one comment to the PR (the independent final-head review
+        # body handed over by the request — never the executor's own
+        # approval).
+        def create_comment(owner:, repo:, index:, body:)
+          translate_mutation do
+            provider(owner, repo).create_comment(index, body)
+          end
+        end
+
+        private
+
+        # One repository-scoped provider client per exchange: the origin is
+        # narrowed with the forge identity this receiver already pinned
+        # against the host-installed configuration, and the scoped token
+        # rides the provider transport instead of any local credential.
+        def provider(owner, repo)
+          Ace::Git::Forgejo::PullRequestApi.new(
+            server: Ace::Git::ResolvedServer.new(name: "lab-forge-merge",
+              provider: :forgejo, url: "#{@base_url}/#{owner}/#{repo}"),
+            timeout: @timeout_seconds, token: @token
+          )
+        end
+
+        # Closed mutation translation: the provider returns an outcome only
+        # for statuses whose meaning is endpoint-specific (2xx success and
+        # the refusal family); everything else it raises as the shared
+        # taxonomy, which maps to :refused (authentication — a definitive
+        # refusal), :ambiguous (unknown outcome), or Unavailable (a read
+        # classified as unreachable).
+        def translate_mutation
+          outcome = yield
+          if (200..299).cover?(outcome.status)
+            Result.new(outcome: :invoked, status: outcome.status, reason: nil)
+          else
+            Result.new(outcome: :refused, status: outcome.status,
+              reason: outcome.message || "HTTP #{outcome.status}")
+          end
+        rescue Ace::Git::ProviderAuthenticationError => e
+          Result.new(outcome: :refused, status: nil, reason: e.message)
+        rescue Ace::Git::ProviderUnknownOutcomeError => e
+          Result.new(outcome: :ambiguous, status: nil, reason: e.message)
+        rescue Ace::Git::Error => e
+          raise Unavailable, e.message
+        end
+      end
+    end
+  end
+end

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

@@ -64,19 +64,13 @@ module Ace
             parse_grants(content, trusted_path)
           end
 
-          private
-
-          def verify_error(path)
-            "invalid lab configuration: trusted authorization file #{path} failed the deployment " \
-              "ownership verification or could not be read; failing closed " \
-              "(required: every traversed element root-owned and not group/world-writable)"
-          end
-
-          # Read the grants document only after proving the deployment owns
-          # the storage along the original path. Genuine absence is nil
-          # (nobody authorized); every other filesystem failure — including
-          # races between lstat and open — classifies fail-closed
-          # (review rounds 6-7, F2).
+          # Read a deployment-owned file only after proving the deployment
+          # owns the storage along the original path (same trust rules as
+          # `resolve`). Genuine absence is nil; every other filesystem
+          # failure — including races between lstat and open — classifies
+          # fail-closed (review rounds 6-7, F2). Public so other trusted
+          # host-installed documents (e.g. the forge merge service identity)
+          # read through the same verification.
           # @return [String, nil] file content, or nil when absent
           def read_verified(path)
             candidate = begin
@@ -104,6 +98,14 @@ module Ace
             end
           end
 
+          private
+
+          def verify_error(path)
+            "invalid lab configuration: trusted authorization file #{path} failed the deployment " \
+              "ownership verification or could not be read; failing closed " \
+              "(required: every traversed element root-owned and not group/world-writable)"
+          end
+
           # Walk the ORIGINAL path component by component. Symlinks are
           # followed only when the link itself is root-owned (a caller-writable
           # redirect is rejected); symlink permission bits are ignored because