ace-lab 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ad491380d732534c8ae2cbabe68bb796cf997adb19ff6dbdb4b6b66353470c6
-  data.tar.gz: c1ba284a9cf628746450b50e1ecf6dcc03589a771fc6f1d44c2eded6afa24861
+  metadata.gz: bb4f48b950b3a32e27a457e36af99148a65e8a95cdbbc55a1586e4f9f2d2abd9
+  data.tar.gz: 361f1a4f8b0167365fe8fee52c7e78047c0f31a9d8f1b1dd9644de79e13b540f
 SHA512:
-  metadata.gz: d6c8605dabf1a3f4bdac9f39a8afeac4c606c30832380f4b93921fc91d9bcd3ac364d1056fbb426130d25bf23410abd29cbd1dd80ec31ad99a563fe224f2c3bc
-  data.tar.gz: d8ca70d0072169a318b7bf2cc57d291f6d9db14250c5af774920e0fb212735570ede41fdc360c1e099f8a41d4de43355bd1e7e6a7aca8a86fef8a21289ba04de
+  metadata.gz: c556ae2dfb4f3137d2e3a45473287c385cc265b2da115aa9db6a2fe42b1e1e61b5a4e6839d98b4b76ce093ace09032c1e8795373f41b33987c0e0127ba1e084a
+  data.tar.gz: 7d470523a46606f392ea1ed22cffd708861c5e635c34ff9d1321ff64d542ef45f30e5cc763ac422ec28a9add7c7ef6a26e8fb705d01f25cdfba291746c19c520

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-16
+
+### Added
+
+- Compose ordinary Assign, HITL and Forgejo merge under one installed owner and journal, with readiness barriers and fresh native/project admission.
+- Optionally serve existing mTLS HITL beside the ordinary Unix listener under the same canonical owner, journal, proposal policy and one-use OTP vault. Validate the configured project and service identity before either listener starts.
+- Add retained assignment prepare/request clients and bounded canonical worktree observations. Separate stable configuration identity from changing decisions, preserve no-effect settlement after slow provider calls, and clean delivery handler process groups.
+- This source cut enables initial installation; it does not claim autonomous release or installed two-project acceptance.
+
+## [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

data/docs/usage.md

@@ -121,6 +121,161 @@ Only the original OS caller identity with project visibility can read the
 request. The authoritative state survives loss of the local assignment cache
 because it lives in the separate assignment evidence Git ref.
 
+### `ace-lab service listen --mode ordinary-merge`
+
+The installed ordinary service owns the Assign, HITL and merge endpoints in one
+process. Start it as the configured service account:
+
+```sh
+ace-lab service listen --mode ordinary-merge --project atlas \
+  --config /etc/lab/ace-lab/atlas-receiver.yml
+```
+
+The receiver configuration selects its existing forge, repository, principal and
+merge socket. `/etc/lab/ace-lab/assign-owners.yml` separately selects the canonical
+Assign journal and native execution owner. Both selections must agree with the
+ordinary project mapping in the trusted authorization document. `repo_path` is
+the merge candidate repository; it does not choose the execution journal.
+
+Each project entry in the root-installed assignment document contains:
+
+| Entry | Installed selection |
+|---|---|
+| `service` | Non-root owner UID/GID, assignment socket and private state root |
+| `journal` | Service-owned repository, execution ref and private evidence checkout |
+| `assignment_root`, `lifecycle_root` | Separate private prepared-input and exclusion directories |
+| `runtime_binary`, `native` | Installed executable and exact native server/socket generation from the installation receipt |
+| `worktrees` | Allowed worktree root and Git common directory |
+| `participants` | OS UID/GID/actor, native workspace and supervisor panes |
+| `hitl` | Private store root, distinct socket, dedicated group, trusted grants path and optional installed TLS authority reference |
+
+For example, the `hitl` entry inside an already selected project can be:
+
+```yaml
+hitl:
+  root: /var/lib/lab/assign/atlas/hitl
+  socket_path: /run/lab/assign/atlas/hitl.sock
+  group: atlas-lifecycle
+  grants_path: /etc/lab/ace-lab/authorization.yml
+```
+
+The store must be a separate child of that project's `service.state_root`; the
+installer creates `service.state_root` with mode `0700`, the HITL root with its
+maintained mode `0711`, and socket access before startup. The private parent keeps
+the HITL tree inaccessible to other accounts; Store maintains private request and
+secret subdirectories. Startup and restart validate the same layout.
+`hitl.service_uid` in the grants document must equal the Assign owner UID. Native
+identities come from the installed receipt and live observation, not the project
+configuration cascade. HITL requests, decisions and merge claims use the same
+canonical Assign journal and lifecycle exclusion.
+
+For the existing remote Hermes transport, install its project-scoped mTLS
+authority and add its absolute configuration path to this same `hitl` entry:
+
+```yaml
+  tls_authority: /etc/lab/ace-hitl/atlas-tls.json
+```
+
+The referenced file uses the maintained `ace.hitl.tls.authority/v1` schema and
+credential provisioning layout from `ace-hitl`. Its project must match this
+owner; `service_user` and `service_group` must resolve to the owner's actual UID
+and primary GID. The dedicated Unix control group remains `hitl.group`. Root
+installs the credential references and Incus TCP proxy; callers cannot choose
+them. Invalid ownership, identity, project or TLS material prevents startup.
+
+The TLS listener runs in this same service process and shares its exact HITL
+binding, store, decision policy and in-memory one-time OTP vault. Hermes uses its
+verified project certificate as a remote transport identity; it does not need a
+synthetic Unix transport UID. Keep `transport_uids` empty when no local transport
+is installed. Configure the actual local proposer separately with
+`proposal_uids` and its project grant. A proposer grant never authorizes replies
+or delegates silence-based decisions. Restart the composed service after changing
+its TLS authority or credential selection, retaining the canonical journal.
+
+All selected endpoints must become ready before assignment ingress opens. A
+failed endpoint shuts down the complete owner. A stale assignment endpoint needs
+installer inspection; startup does not remove it or recover merge effects first.
+
+## Ordinary assignment client
+
+`ace-lab assignment` selects the root-installed project owner and uses the
+existing Assign protocol. Assign remains the only accepted execution journal.
+Preparation captures reviewed task context and the existing managed assignment
+graph; it does not start a worker or register accepted work.
+
+```sh
+ace-lab assignment prepare --project atlas --task 8wr.t.abc --pane w1:pS \
+  --output .ace-local/prepared-task
+ace-lab assignment request --project atlas --input .ace-local/prepared-task/request.json
+```
+
+The output directory must not exist. Preparation retains the definition, bundle,
+and registration request with one stable mutation ID. `--dependency-reports FILE`
+selects an explicit JSON array of `{task_id, assignment_id, number}` entries for
+dependency reports. A failed preparation keeps partial files for inspection;
+it never rebuilds an existing directory. In this source checkout use
+`bundle exec ace-lab` because no `bin/ace-lab` binstub is committed.
+
+Every request file has exactly these fields:
+
+```json
+{
+  "version": 1,
+  "project_id": "atlas",
+  "operation": "start_attempt",
+  "mutation_id": "original-start-001",
+  "params": {
+    "assignment_id": "assignment-id",
+    "attempt_id": "attempt-id",
+    "expected_generation": 0,
+    "scope": "010",
+    "head": "0123456789012345678901234567890123456789",
+    "pane": "w1:p2"
+  },
+  "parts": []
+}
+```
+
+Use actual retained IDs, scope, head and native pane. The actual worker executes
+its start request: the owner verifies caller ancestry, live process and checkout.
+A supervisor cannot impersonate another pane by changing `pane`. A new terminal
+or prompt acknowledgement alone is not running proof.
+
+| Operation | `params` beyond `assignment_id` | Transfer / authority |
+|---|---|---|
+| `register_assignment` | Generated by prepare | Exact prepared bundle; supervisor |
+| `registration_status` | None | Read; `mutation_id: null` |
+| `start_attempt` | `attempt_id`, `expected_generation: 0`, `scope`, `head`, `pane` | Actual worker start |
+| `assignment_snapshot` | `attempt_id` (or null), `kind: queue` or `prepared_work` | Download; `mutation_id: null` |
+| `queue_start` | `attempt_id`, `expected_generation`, `pane`, `step` (or null for next) | Original worker |
+| `queue_finish` | Same as queue_start | One UTF-8 report part |
+| `queue_fail` | `attempt_id`, `expected_generation`, `pane`, `message` | Original worker; unfinished work stays failed |
+| `submit_result` | `attempt_id`, `expected_generation`, `pane`, `head`, `receipt_sha256` | Receipt first, then its ordered artifacts; original worker |
+| `result_status` | `attempt_id` | Read; `mutation_id: null` |
+| `result_snapshot` | `attempt_id`, `result_id` | Canonical receipt/artifacts download; `mutation_id: null` |
+| `finish` | `attempt_id`, `expected_generation`, `pane`, `head`, `result_id`, `receipt_digest` | Supervisor accepts exact submitted result after settlement |
+
+Upload `parts` are ordered `{file, bytes, sha256}` entries. Relative files resolve
+beside the retained request. Changed, oversized or symlinked inputs refuse before
+connection. Requesters never supply a wire `transfer` descriptor. Downloads require
+`--output NEW_DIRECTORY`; numbered byte files and `response.json` are private
+projections of the authenticated reply, not another execution store. For queue
+snapshots, the first byte file contains the current step instructions and reports
+as JSON; prepared-work snapshots contain the original Git bundle.
+
+Retain each request and its exact parts before invoking it. On response loss,
+inspect `registration_status` or `result_status` and reuse the same original
+mutation when replay is appropriate. Never refresh its generation, replace its
+bytes, or create a second worker because a reply was lost. Queue completion and
+`submit_result` keep the attempt running; only the canonical accepted `finish`
+reply proves terminal completion. Unknown effect or Inbox settlement refuses it.
+
+These commands do not silently route to a local `ace-assign` cache. Missing or
+changed installed owner selection is an explicit failure. Native wake consumers
+must read the same canonical status and adopt its original attempt/result IDs.
+Changed owner selection refuses new admission and dispatch until a controlled
+restart. Existing canonical receipts remain the source for reconciliation.
+
 ## Error semantics
 
 Errors are one deterministic JSON document on stdout plus a non-zero exit.

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../../organisms/ordinary_assignment_client"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        module Assignment
+          class Prepare < Ace::Support::Cli::Command
+            desc "Retain reviewed task input for ordinary Assign registration"
+            option :project, required: true, desc: "Installed project ID"
+            option :task, required: true, desc: "Reviewed leaf task ID"
+            option :pane, required: true, desc: "Actual supervisor pane for registration"
+            option :output, required: true, desc: "New private directory for retained input"
+            option :dependency_reports, desc: "JSON array of explicit dependency report selections"
+
+            def call(project:, task:, pane:, output:, **options)
+              reports = options[:dependency_reports] ? JSON.parse(Organisms::OrdinaryAssignmentClient.read_file(
+                options.fetch(:dependency_reports), 65_536), allow_duplicate_key: false, create_additions: false, max_nesting: 16) : []
+              puts JSON.generate(Organisms::OrdinaryAssignmentClient.prepare(project: project, task: task,
+                pane: pane, output: output, dependency_reports: reports))
+            rescue JSON::ParserError, ArgumentError, KeyError, SystemCallError, Ace::Assign::Error, Ace::Runtime::Error => error
+              raise Ace::Support::Cli::Error, "ordinary preparation incomplete: #{error.message}; retain existing files"
+            end
+          end
+
+          class Request < Ace::Support::Cli::Command
+            desc "Send one retained operation to the installed ordinary Assign owner"
+            option :project, required: true, desc: "Installed project ID"
+            option :input, required: true, desc: "Retained request JSON with original mutation and part digests"
+            option :output, desc: "New private directory for a canonical snapshot download"
+
+            def call(project:, input:, **options)
+              service = Organisms::OrdinaryAssignmentClient.new(project: project)
+              puts JSON.generate(service.request(input: input, output: options[:output]))
+            rescue ArgumentError, KeyError, SystemCallError, Ace::Assign::Error, Ace::Runtime::Error, Ace::Lab::Error => error
+              raise Ace::Support::Cli::Error, "ordinary assignment unavailable: #{error.message}; retain the original request; inspect status before new work"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,6 +6,10 @@ 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 "../../organisms/ordinary_authority_composition"
+require_relative "../../molecules/ordinary_listener"
+require_relative "../../molecules/ordinary_receiver_config"
 
 module Ace
   module Lab
@@ -169,6 +173,66 @@ module Ace
               @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 OS peer credentials, 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 ordinary Assign, HITL and fixed merge under the installed journal owner"
+            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
+              unless receiver_config.receiver_uid == Process.uid
+                raise Ace::Lab::InvalidConfigurationError, "receiver must run as its configured UID"
+              end
+              server = Organisms::OrdinaryAuthorityComposition.new(receiver_config: receiver_config).build
+              signals = %w[INT TERM].to_h { |signal| [signal, Signal.trap(signal) { server.request_stop }] }
+              server.serve
+            rescue Ace::Lab::InvalidConfigurationError, Ace::Assign::Error, Ace::Runtime::Error, Ace::Hitl::Lifecycle::Error => e
+              emit(Organisms::OrdinaryMergeRequest.refusal_envelope(
+                "ordinary_merge_unavailable", e.message,
+                request_id: "unknown", input_digest: nil
+              ))
+            ensure
+              signals&.each { |signal, handler| Signal.trap(signal, handler) }
+            end
+          end
         end
       end
     end

data/lib/ace/lab/cli.rb

@@ -9,6 +9,7 @@ require_relative "cli/commands/services"
 require_relative "cli/commands/resolve"
 require_relative "cli/commands/route"
 require_relative "cli/commands/service"
+require_relative "cli/commands/assignment"
 
 module Ace
   module Lab
@@ -26,7 +27,10 @@ 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"],
+        ["assignment prepare", "Retain reviewed task input for ordinary Assign registration"],
+        ["assignment request", "Send one retained operation to the installed ordinary Assign owner"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -52,6 +56,9 @@ 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 "assignment prepare", CLI::Commands::Assignment::Prepare.new
+      register "assignment request", CLI::Commands::Assignment::Request.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