ace-git-forgejo 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7388b7c2b27b633234131dca7f190a344c7e1f323e23e2e01b532ed3a16407a
-  data.tar.gz: 3960cdfc787b85500050589ac27b1a8bceb8d3e5cd594eb37db2448d7e314426
+  metadata.gz: cf55e32720105f61ee776ab2e828cc52eff70422d40169c3ec473faa8918852e
+  data.tar.gz: d53c30cfdd65d9efd401846871c8572a48442c68d280a0615e7d9b04c8792b45
 SHA512:
-  metadata.gz: 77a634e5f5f9de6c004a2585e57379104062f11e6eee34532edb390c8200aeaba6d3fc3433ec21ccc6e6ee1a1a3aca22b47b99e83890982e9f8d4ef7400bd045
-  data.tar.gz: c13861e169c6bb26db7bde14c400186677f01c70c185bec7d07a374b6fdcde08717b27ef7233900da128072587af39393af5dc0584603085d0c8293eeba9aff1
+  metadata.gz: c3d888812cbbec6e223ddfca72514bbee53f3281374825b4147c4f1ebc3fd415528f4fc5c08eafadb6cfed35df6acac4220955f629e15b90dc593d91ceee963c
+  data.tar.gz: 9dd8b2e6fed777a0c038b111e448c536c0a960c7a7ff53e6d0d9ca1e200bd083e591cb35bf6d7943ec552e206b006021a7314b9bb615e93a9df1a34e179c1f98

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-04
+
+### Added
+- Complete PR delivery lifecycle over the repository-bound Forgejo API v1: create with canonical and same-server fork heads and exact draft state, mark-ready, and merge with the server-enforced `head_commit_id` expected-head precondition (minimum supported server: Forgejo 8.0 — first line enforcing the merge precondition and reporting the API draft field — probed before mutations).
+- Authoritative pull request reads from the API: exact head provenance, draft state, and merge-commit evidence replace the fj view/commits pair for PR identity.
+- Duplicate-create races reconcile to the exact open match; already-merged refusals are reusable only with authoritative merged evidence at the expected source SHA.
+
+### Changed
+- PR reads, lifecycle matching, and updates ride the Faraday HTTP transport (ADR-010) with retries limited to safe GETs and no redirect following; lifecycle mutations are gated on a documented server capability floor and fail closed without it.
+
+### Removed
+- The fj-era refusals for fork creation, draft-to-ready, and expected-head merging; the conservative `fj pr merge`/`pr edit` paths are replaced by the API lifecycle.
+
 ## [0.5.0] - 2026-10-03
 
 ### Added
@@ -75,19 +88,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   precondition atomically, so both refuse instead of racing.
 - PR view parser captures the fork repository prefix of the `From` segment.
 
-### Added
-- PR lifecycle mutations matching the shared provider contract: exact-match
-  lookup via `fj pr search`, idempotent create reconciliation, head-verified
-  title/body updates.
-- Fork provenance: the `fj pr view` head-repository segment is parsed and
-  returned in normalized PR evidence.
-
-### Changed
-- `pr ready` and `pr merge` are classified unsupported capabilities: `fj`
-  offers no draft-to-ready command and cannot enforce an expected-head merge
-  precondition atomically, so both refuse instead of racing.
-- PR view parser captures the fork repository prefix of the `From` segment.
-
 ## [0.1.1] - 2026-09-28
 
 

data/README.md

@@ -36,16 +36,15 @@ forbidden; there is no silent fallback of any kind.
 
 ## Supported operations (observed on forgejo-cli v0.6.0)
 
-PR view/diff/head-commits, PR search (all/open, client-side newest-first
-window — `fj` has no `--limit`), PR create (same-repository head only),
-PR edit title/body, issue view, actions tasks, repository view, version
-and `auth list` probes. `fj` v0.6.0 exposes no draft-to-ready command, no
-atomic expected-head merge, and no authoritative merge-commit field, so
-`ready_pull_request`/`merge_pull_request` refuse as unsupported
-capabilities and `merge_commit_sha` stays empty — worktree cleanup
-conservatively retains Forgejo checkouts until `fj` exposes that field.
-The capability evidence and its provenance live in the
-`8wr.t.uj0` task folder (`evidence/fj-capabilities.md`).
+Through `fj` (observed on forgejo-cli v0.6.0): PR view/diff/head-commits,
+PR search (all/open, client-side newest-first window — `fj` has no
+`--limit`), issue view, actions tasks, repository view, version and
+`auth list` probes. Through the repository-bound API v1: authoritative PR
+reads, PR create (canonical and same-server fork heads, exact draft
+state), edit, ready transitions, and expected-head-guarded merges — see
+the delivery lifecycle section below. The per-surface capability evidence
+and its provenance live in the `8wr.t.uj0` (`evidence/fj-capabilities.md`)
+and `8x2.t.z78` (`capability-evidence-2026-10-04.md`) task folders.
 
 Endpoint fidelity: `-H` carries the selected `scheme://authority` (fj
 otherwise assumes HTTPS), and because fj v0.6.0 silently applies its
@@ -54,3 +53,46 @@ observed keys-file locations and refuses a repository command when an
 alias redirects the selected host — never modifying user fj
 configuration; an absent or unreadable keys file is allowed.
 
+## PR delivery lifecycle (Forgejo API v1)
+
+The delivery lifecycle — create (canonical and same-server fork sources,
+exact draft state), mark-ready, and merge with a server-enforced
+expected-head precondition — rides the repository-bound Forgejo REST API
+v1 through the same selected host and `fj` token as the review transport.
+The `fj` v0.6 CLI cannot encode a fork head, an explicit draft state, a
+ready transition, or an atomic merge precondition, so those operations do
+not approximate it with check-then-act sequencing.
+
+Minimum supported server: **Forgejo 8.0** (the first line that both
+enforces the documented `MergePullRequestOption.head_commit_id` merge
+precondition server-side and reports the API `draft` field; the provider
+probes `/api/v1/version` and refuses lifecycle mutations below the
+floor). Official capability evidence lives in the
+`8x2.t.z78` task folder (`capability-evidence-2026-10-04.md`).
+
+Forgejo-specific conventions the provider translates:
+
+- **Drafts**: the create/edit API forms have no writable draft field —
+  a draft is a WIP-prefixed title (server defaults `WIP:`, `[WIP]`;
+  compared case-insensitively). The server reports the computed boolean
+  in the API `draft` response field, which this provider treats as the
+  only draft truth on reads. Create with
+  `draft: true` prefixes the title `WIP: `; `draft: false` refuses a
+  WIP-prefixed title instead of silently publishing it as a draft. Ready
+  strips one leading prefix and proves the resulting `draft: false` by
+  read-back. A draft whose title carries no known prefix refuses before
+  the mutation (the server likely uses configured prefixes).
+- **Merge** sends the full expected SHA in `head_commit_id`; Forgejo
+  re-resolves the head ref inside the merge and refuses with 409 when it
+  moved. The provider classifies that as
+  `ProviderExpectedHeadConflictError` and never pre-reads as a substitute
+  guard. A 409 that reads back as already merged at the expected source
+  SHA, with a merge commit, is reusable authoritative evidence.
+- **Reconciliation**: a transport failure on any mutation raises
+  `ProviderUnknownOutcomeError` carrying the exact identity; nothing is
+  retried automatically. A duplicate-create 409 reconciles to the exact
+  open match; mutation outcomes are proven by authoritative read-backs
+  (head unchanged, requested state, merged evidence).
+
+Identical lifecycle assertions run against every provider through the
+shared `Ace::TestSupport::PullRequestLifecycleContract` parity suite.

data/lib/ace/git/forgejo/http_client.rb

@@ -2,9 +2,9 @@
 
 require "digest"
 require "json"
-require "net/http"
+require "faraday"
+require "faraday/retry"
 require "openssl"
-require "uri"
 require_relative "repository_binding"
 
 module Ace
@@ -12,6 +12,13 @@ module Ace
     module Forgejo
       # Authenticated, repository-bound JSON transport for Forgejo API
       # capabilities whose fj v0.6 output omits stable object IDs.
+      #
+      # Live traffic uses Faraday (ADR-010): no redirect middleware is
+      # installed (a redirect must never carry credentials or a write to
+      # another host; the configured endpoint is verified up front by
+      # {RepositoryBinding.reject_selected_host_redirect!}), and retries are
+      # limited to the safe GET verb — a mutation is sent at most once per
+      # call, so a lost response stays an unknown outcome.
       class HttpClient
         def initialize(server:, timeout:, runner: nil)
           @target = RepositoryBinding::Target.resolve(server.url)
@@ -44,40 +51,97 @@ module Ace
           entries
         end
 
+        # Send one request and classify every non-success status with the
+        # shared taxonomy.
+        #
+        # @return [Object, nil] parsed JSON body (nil when empty)
         def request(method, suffix, body: nil)
+          status, payload = exchange(method, suffix, body: body)
+          classify_status!(status, method, exchange_path(suffix))
+          payload
+        end
+
+        # Send one request and return the raw HTTP outcome so endpoint-aware
+        # callers can classify statuses the generic map cannot distinguish
+        # (e.g. a 409 that may mean "already exists" on create or "head out
+        # of date" on merge). Transport failures still classify by method:
+        # reads are unreachable, mutations are unknown outcomes.
+        #
+        # @return [Array(Integer, Object, nil)] status, parsed JSON body
+        #   (nil when empty), and the server-supplied error message for
+        #   non-success statuses (sanitized, truncated)
+        def exchange(method, suffix, body: nil)
           RepositoryBinding.reject_selected_host_redirect!(@target.host_url)
-          path = "/api/v1/repos/#{@target.repo}/#{suffix}"
+          path = exchange_path(suffix)
           if @runner
             result = @runner.call(args: ["forgejo-http", method.to_s.upcase, "#{@target.host_url}#{path}", body],
               timeout: @timeout, env: {})
             status = result[:status] || (result[:success] ? 200 : 503)
             payload = result[:stdout].to_s
           else
-            uri = URI.parse("#{@target.host_url}#{path}")
-            klass = {get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch}.fetch(method)
-            req = klass.new(uri)
-            req["Authorization"] = "token #{access_token!}"
-            req["Accept"] = "application/json"
-            req["Content-Type"] = "application/json" if body
-            req.body = JSON.generate(body) if body
-            response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-              open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(req) }
-            status = response.code.to_i
+            response = connection(method).send(method, path) do |req|
+              req.headers["Content-Type"] = "application/json" if body
+              req.body = JSON.generate(body) if body
+            end
+            status = response.status
             payload = response.body.to_s
           end
-          classify_status!(status, method, path)
-          return nil if payload.empty?
-
-          JSON.parse(payload)
-        rescue JSON::ParserError => e
-          raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo response: #{e.message}"
-        rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, IOError, SocketError, OpenSSL::SSL::SSLError, SystemCallError => e
+          [status, parse_payload(payload), server_error_message(payload)]
+        rescue Faraday::TimeoutError, Faraday::ConnectionFailed, IOError, SocketError,
+               OpenSSL::SSL::SSLError, SystemCallError => e
           error = (method == :get) ? Ace::Git::ProviderUnreachableError : Ace::Git::ProviderUnknownOutcomeError
           raise error, "Forgejo #{method} #{path} outcome unknown: #{e.class}"
         end
 
         private
 
+        # Suffixes already carrying the API root are used verbatim (the
+        # server-level /api/v1/version probe); everything else is
+        # repository-scoped to the selected owner/repo.
+        def exchange_path(suffix)
+          return suffix if suffix.to_s.start_with?("/api/v1/")
+
+          "/api/v1/repos/#{@target.repo}/#{suffix}"
+        end
+
+        # A non-JSON body is an absent payload, not a parse failure: the
+        # status carries the outcome, and every consumer validates the shape
+        # of what it reads, so malformed evidence still fails closed.
+        def parse_payload(payload)
+          return nil if payload.nil? || payload.empty?
+
+          JSON.parse(payload)
+        rescue JSON::ParserError
+          nil
+        end
+
+        # The forge's own explanation for a failed status, sanitized: only
+        # the JSON `message` string survives, truncated, so tokens and raw
+        # response bodies never reach an error message.
+        def server_error_message(payload)
+          parsed = parse_payload(payload)
+          return nil unless parsed.is_a?(Hash) && parsed["message"].is_a?(String)
+
+          message = parsed["message"].strip
+          message.empty? ? nil : message[0, 300]
+        end
+
+        # Connection per HTTP method: the retry middleware is installed only
+        # for the safe verb so a mutation can never be silently re-sent.
+        def connection(method)
+          @connections = {} unless @connections.is_a?(Hash)
+          @connections[method] ||= Faraday.new(url: @target.host_url) do |faraday|
+            faraday.options.timeout = @timeout
+            faraday.options.open_timeout = @timeout
+            faraday.headers["Accept"] = "application/json"
+            faraday.headers["Authorization"] = "token #{access_token!}"
+            if method == :get
+              faraday.request :retry, max: 2, methods: [:get], retry_if: ->(_env, _result) { false }
+            end
+            faraday.adapter Faraday.default_adapter
+          end
+        end
+
         def access_token!
           path = RepositoryBinding.default_keys_path
           data = path && JSON.parse(File.read(path))

data/lib/ace/git/forgejo/provider.rb

@@ -2,28 +2,36 @@
 
 require "json"
 require "uri"
+require "ace/git/atoms/server_url"
 require_relative "cli_executor"
+require_relative "repository_binding"
 require_relative "parsers"
 require_relative "issue_api"
+require_relative "pull_request_api"
 
 module Ace
   module Git
     module Forgejo
       # Forgejo provider implementation of the shared provider contract.
       #
-      # Owns Forgejo terminology and translates `fj` responses into the
-      # normalized evidence types defined by the ace-git core. Every
-      # repository-scoped call is bound to the selected server's exact
-      # host/owner/repository through the {CliExecutor} repository boundary:
-      # the selected identity is mandatory, unobserved operations refuse
-      # before launch, and returned evidence is checked for conflicting
-      # identity. Every failure is classified with the shared taxonomy;
-      # `fj` failures are never hidden behind ad-hoc curl calls or silent
-      # fallbacks.
+      # Owns Forgejo terminology and translates `fj` and Forgejo API v1
+      # responses into the normalized evidence types defined by the ace-git
+      # core. Every repository-scoped call is bound to the selected server's
+      # exact host/owner/repository: `fj` commands through the {CliExecutor}
+      # repository boundary, API calls through the repository-bound
+      # {HttpClient}/{PullRequestApi} routes. The selected identity is
+      # mandatory, unobserved operations refuse before launch, and returned
+      # evidence is checked for conflicting identity. Every failure is
+      # classified with the shared taxonomy; provider failures are never
+      # hidden behind ad-hoc curl calls or silent fallbacks.
       class Provider < Ace::Git::Providers::Base
         # Fill color for repo labels created on demand by issue linking.
         TRACKED_LABEL_COLOR = "0e8a16"
 
+        # Forgejo's default work-in-progress title prefixes; the server
+        # derives its API `draft` field from them (case-insensitive).
+        WIP_PREFIXES = ["WIP:", "[WIP]"].freeze
+
         class << self
           def display_name
             "Forgejo"
@@ -51,12 +59,18 @@ module Ace
           CliExecutor.check_authenticated!(authority: repository_target.authority, runner: runner)
         end
 
+        # Authoritative pull request read. One API payload binds the exact
+        # head repository/ref/SHA, draft state, and merge evidence that the
+        # fj surface cannot report (no draft field, head SHA only via a
+        # second command); contradictory or missing identity fails closed.
+        #
         # @return [ProviderPullRequest] normalized pull request evidence
-        # @raise [ProviderObjectNotFoundError] when the PR does not exist
-        # @raise [ProviderMalformedOutputError] when `fj` output is unexpected
-        # @raise [ProviderUnreachableError] when the endpoint is unreachable
+        # @raise [Ace::Git::ProviderObjectNotFoundError] when the PR does not exist
+        # @raise [Ace::Git::ProviderMalformedOutputError] when the payload is unexpected
+        # @raise [Ace::Git::ProviderUnreachableError] when the endpoint is unreachable
         def pull_request(number:)
-          fetch_pr(number)
+          number = request_number!(number)
+          normalize_api_pr(pr_api.pull_request(number))
         end
 
         # @return [ProviderPullRequest, nil] evidence for the branch's PR
@@ -252,7 +266,7 @@ module Ace
           number = request_number!(number)
           verify_expected_head!(pull_request(number: number), expected_head)
           comments = review_http.paginate("issues/#{number}/comments").map do |entry|
-            review_comment(entry, number, expected_head)
+            review_comment(entry, number)
           end
           reviews = review_http.paginate("pulls/#{number}/reviews").map do |entry|
             review_entry(entry, number, expected_head)
@@ -266,7 +280,7 @@ module Ace
             unless entries.is_a?(Array)
               raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo review comment evidence"
             end
-            entries.map { |entry| review_comment(entry, number, expected_head) }
+            entries.map { |entry| review_comment(entry, number) }
           end
           verify_expected_head!(pull_request(number: number), expected_head)
           Ace::Git::ProviderReviewEvidence.new(
@@ -322,7 +336,7 @@ module Ace
           require_open_pr!(pr)
           marker = comment_marker(correlation)
           with_session_lock(correlation) do
-          existing = matching_review_comments(number, marker, expected_head)
+          existing = matching_review_comments(number, marker)
           if existing.length > 1
             raise Ace::Git::ProviderConflictingMatchesError,
               "Multiple comments match review session #{correlation} on PR ##{number}"
@@ -352,7 +366,7 @@ module Ace
               "session #{correlation}: #{e.message}; reconcile before repeating"
           end
           begin
-          matches = matching_review_comments(number, marker, expected_head)
+          matches = matching_review_comments(number, marker)
           rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
             raise Ace::Git::ProviderUnknownOutcomeError,
               "PR comment sent but reconciliation read failed for session #{correlation}: #{e.message}; reconcile before repeating"
@@ -385,7 +399,7 @@ module Ace
             raise Ace::Git::ProviderIdentityMismatchError,
               "Comment #{comment_id} does not belong to selected PR ##{number}"
           end
-          comment = review_comment(matches.first, number, expected_head)
+          comment = review_comment(matches.first, number)
           if comment.body == body
             verify_post_mutation_head!(number, expected_head, "comment #{comment_id}")
             return review_mutation(number, expected_head, comment, :existing)
@@ -423,7 +437,7 @@ module Ace
               "Comment update sent but exact PR comment #{comment_id} could not be verified"
           end
           verify_post_mutation_head!(number, expected_head, "comment #{comment_id}")
-          review_mutation(number, expected_head, review_comment(updated, number, expected_head), :updated)
+          review_mutation(number, expected_head, review_comment(updated, number), :updated)
         end
 
         def resolve_pull_request_thread(number:, expected_head:, thread_id:)
@@ -432,39 +446,38 @@ module Ace
         end
 
         # ---- PR lifecycle mutations ----
+        #
+        # Delivery-capable lifecycle on the documented Forgejo API v1
+        # (capability evidence in the task report): canonical and
+        # same-server fork heads via the "owner:branch" head form, draft
+        # state via the WIP title convention the server itself derives
+        # draft from, and merges guarded by the server-enforced
+        # `head_commit_id` precondition.
 
         # @return [Array<ProviderPullRequest>] open PRs matching the exact
-        #   base/head identity, with head SHA provenance
+        #   base/head identity, with head SHA provenance from the API list
         def find_open_pull_requests(head_repository_url:, head_ref:, base_repository_url:, base_ref:)
           require_base_on_server!(base_repository_url)
-          listing = fj(:pr_search, "open")
-          Parsers.parse_search(listing).filter_map do |entry|
-            parsed = view_pr(entry[:number])
-            next unless parsed && parsed[:state] == :open
-            next unless parsed[:head_ref] == head_ref && parsed[:base_ref] == base_ref
-            next unless Ace::Git::Atoms::ServerUrl.match?(head_repository_url_of(parsed), head_repository_url)
-
-            with_head_sha(parsed)
+          # An absent head repository names the base repository itself,
+          # mirroring the lifecycle organism's default.
+          head_repository_url = server.url if head_repository_url.to_s.empty?
+          pr_api.open_pull_requests.filter_map do |payload|
+            next unless payload.dig("head", "ref") == head_ref && payload.dig("base", "ref") == base_ref
+            next unless Ace::Git::Atoms::ServerUrl.match?(api_head_repository_url(payload), head_repository_url)
+
+            normalize_api_pr(payload)
           end
         end
 
-        # Create a PR via `fj pr create`, reconciling to an exact open match
-        # first and proving the resulting head against `expected_head`.
-        # `fj` cannot encode an explicit fork head; the receipt reports the
-        # provider's real draft state.
+        # Create (or reconcile to) a pull request for the exact identity.
+        # Same-server fork sources are encoded with the documented
+        # "owner:branch" API form; cross-host sources are refused before
+        # any request. The requested draft state is preserved exactly, and
+        # an existing exact match is reusable only when its draft state
+        # agrees; a duplicate-create race reconciles to the winner.
         #
         # @return [ProviderMutationReceipt] idempotency :created/:existing
         def create_pull_request(head_ref:, head_repository_url:, base_ref:, expected_head:, title:, body: nil, draft: true)
-          # `fj pr create -r` binds the base repository, but no observed form
-          # encodes a cross-repository fork head; refusing before any command
-          # (even lookups) beats creating the wrong PR.
-          unless Ace::Git::Atoms::ServerUrl.match?(head_repository_url, server.url)
-            raise Ace::Git::ProviderUnsupportedCapabilityError,
-              "Forgejo CLI (fj) pr create cannot target head repository " \
-              "#{head_repository_url} (resolved server repository: #{server.url}); " \
-              "run from the fork checkout or use the forge web UI"
-          end
-
           matches = find_open_pull_requests(
             head_repository_url: head_repository_url, head_ref: head_ref,
             base_repository_url: server.url, base_ref: base_ref
@@ -475,53 +488,363 @@ module Ace
               "#{base_ref}: #{matches.map(&:number).join(", ")}; resolve the conflict first"
           end
           if matches.size == 1
-            return receipt(:create, verify_expected_head!(matches.first, expected_head), :existing)
+            existing = verify_expected_head!(matches.first, expected_head)
+            ensure_draft_agreement!(existing, draft)
+            return receipt(:create, existing, :existing)
           end
 
-          send_mutation(:pr_create, title, head_ref, base_ref, body,
-            ambiguous: true, identity: identity_text(head_repository_url, head_ref, base_ref))
+          head_arg = api_head_argument!(head_repository_url, head_ref)
+          send_title = draft_title!(title, draft)
+          pr_api.ensure_version_supported!
+          outcome = send_lifecycle_mutation(identity_text(head_repository_url, head_ref, base_ref)) do
+            pr_api.create_pull_request(head: head_arg, base: base_ref, title: send_title, body: body)
+          end
 
-          created = reconcile_created(
-            head_repository_url: head_repository_url, head_ref: head_ref,
-            base_ref: base_ref, expected_head: expected_head
-          )
+          if outcome.status == 409
+            # A concurrent create won the race: the exact match is
+            # authoritative, and repeating the send would never be ours.
+            return reconcile_raced_create(head_repository_url: head_repository_url, head_ref: head_ref,
+              base_ref: base_ref, expected_head: expected_head, draft: draft)
+          end
+          unless outcome.status == 201 && outcome.payload.is_a?(Hash) && outcome.payload["number"].is_a?(Integer)
+            classify_create_refusal(outcome, head_repository_url, head_ref, base_ref)
+          end
+
+          created = verify_expected_head!(pull_request(number: outcome.payload["number"]), expected_head)
+          ensure_draft_outcome!(created, draft)
           receipt(:create, created, :created)
         end
 
-        # `fj pr edit` takes one field subcommand per invocation (title|body),
-        # so multi-field updates are separate commands with final evidence
-        # fetched only after every field update succeeded.
+        # Edit title/body after exact-head verification through the same
+        # API mutation path as the rest of the lifecycle.
         #
         # @return [ProviderMutationReceipt] operation :update
         def update_pull_request(number:, expected_head:, title: nil, body: nil)
           number = request_number!(number)
-          verify_expected_head!(fetch_pr(number), expected_head)
-          send_mutation(:pr_edit_title, number, title, ambiguous: false) if title
-          send_mutation(:pr_edit_body, number, body, ambiguous: false) if body
-          receipt(:update, fetch_pr(number), nil)
+          verify_expected_head!(pull_request(number: number), expected_head)
+          if title || body
+            pr_api.ensure_version_supported!
+            outcome = send_lifecycle_mutation("PR ##{number} on #{server.name}, head #{expected_head}") do
+              pr_api.edit_pull_request(number, title: title, body: body)
+            end
+            unless (200..299).cover?(outcome.status)
+              raise Ace::Git::ProviderUnknownOutcomeError,
+                "PR update refused for ##{number} (HTTP #{outcome.status}: #{outcome.message}); " \
+                "reconcile before repeating"
+            end
+            verify_post_mutation_head!(number, expected_head, "update")
+          end
+          receipt(:update, pull_request(number: number), nil)
         end
 
-        # `fj` offers no draft-to-ready command; classified as an unsupported
-        # capability instead of guessing at provider behavior.
+        # Mark a draft ready on the exact head. Forgejo derives draft state
+        # from the WIP title prefix, so the transition is the documented
+        # title edit with the prefix removed; the resulting ready state and
+        # unchanged head are proven by an authoritative read-back.
+        #
+        # @return [ProviderMutationReceipt] operation :ready
         def ready_pull_request(number:, expected_head:)
-          raise Ace::Git::ProviderUnsupportedCapabilityError,
-            "Forgejo CLI (fj) cannot mark a draft pull request ready; use the forge web UI"
+          number = request_number!(number)
+          pr = verify_expected_head!(pull_request(number: number), expected_head)
+          unless pr.state == :open
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Cannot mark PR ##{number} ready in #{pr.state} state"
+          end
+          # Already-ready at the same head is idempotent.
+          return receipt(:ready, pr, nil) unless pr.draft
+
+          # Refuse an impossible transition before any server traffic; the
+          # capability gate sits directly in front of the mutation.
+          stripped_title = strip_wip_prefix!(pr.title, number)
+          pr_api.ensure_version_supported!
+          outcome = send_lifecycle_mutation("ready transition for PR ##{number} on #{server.name}, head #{expected_head}") do
+            pr_api.edit_pull_request(number, title: stripped_title)
+          end
+          unless (200..299).cover?(outcome.status)
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "Ready transition refused for PR ##{number} (HTTP #{outcome.status}: #{outcome.message}); " \
+              "reconcile before repeating"
+          end
+
+          after = verify_post_mutation_head!(number, expected_head, "ready")
+          unless after.draft == false
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "Ready title applied but PR ##{number} still reports draft on #{server.name}; " \
+              "reconcile before repeating"
+          end
+          receipt(:ready, after, nil)
         end
 
-        # `fj pr merge` cannot enforce an expected-head precondition
-        # atomically, so merging is refused rather than racing a stale head.
+        # Merge with the server-enforced atomic precondition: Forgejo
+        # re-resolves the head ref inside the merge and refuses with 409
+        # when it is not exactly `head_commit_id`. There is deliberately no
+        # pre-read fallback guard. Success (and a refused race that turns
+        # out already merged) is proven by merged state plus the merge
+        # commit on the selected PR at the expected source SHA.
+        #
+        # @return [ProviderMutationReceipt] operation :merge
         def merge_pull_request(number:, expected_head:, method:)
           unless %i[squash merge rebase].include?(method)
             raise ArgumentError, "Invalid merge method #{method.inspect}"
           end
+          number = request_number!(number)
+          pr = verify_expected_head!(pull_request(number: number), expected_head)
+          case pr.state
+          when :open
+            nil # proceed to the guarded merge
+          when :merged
+            # Already merged at the expected source SHA: authoritative
+            # evidence is reusable without another mutation attempt.
+            prove_merged!(pr, expected_head)
+            return receipt(:merge, pr, nil)
+          else
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Cannot merge PR ##{number} in #{pr.state} state"
+          end
 
-          raise Ace::Git::ProviderUnsupportedCapabilityError,
-            "Forgejo CLI (fj) pr merge cannot enforce expected-head (#{expected_head}) " \
-            "atomically; refusing unsafe merge"
+          pr_api.ensure_version_supported!
+          outcome = send_lifecycle_mutation("merge of PR ##{number} on #{server.name}, head #{expected_head}") do
+            pr_api.merge_pull_request(number, do_method: method.to_s, head_commit_id: expected_head)
+          end
+
+          case outcome.status
+          when 200..299
+            after = verify_post_mutation_head!(number, expected_head, "merge")
+            prove_merged!(after, expected_head)
+            receipt(:merge, after, nil)
+          when 409
+            if outcome.message.to_s.match?(/head out of date/i)
+              raise Ace::Git::ProviderExpectedHeadConflictError,
+                "Forgejo refused the merge of PR ##{number}: the head moved past #{expected_head} " \
+                "before the server-side expected-head check (#{outcome.message})"
+            end
+            reconcile_refused_merge(number, expected_head, outcome)
+          when 405
+            if outcome.message.to_s.match?(/try again later/i)
+              # The server's mergeable state was still computing; the merge
+              # was not applied. The caller may retry the same command.
+              raise Ace::Git::ProviderUnreachableError,
+                "Forgejo mergeable state for PR ##{number} is still computing " \
+                "(HTTP 405: #{outcome.message}); the merge was not applied and the " \
+                "command may be repeated"
+            end
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Forgejo refused to merge PR ##{number} as #{method}: #{outcome.message || "merge style unavailable"}"
+          when 404
+            raise Ace::Git::ProviderObjectNotFoundError, "Forgejo pull request ##{number} not found"
+          when 422
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "Forgejo rejected the merge request for PR ##{number} (#{outcome.message})"
+          end
         end
 
         private
 
+        # Send one lifecycle mutation: a transport-level failure after the
+        # send stays an unknown outcome and gains the exact reconciliation
+        # identity; the mutation is never retried inside the provider.
+        def send_lifecycle_mutation(identity)
+          yield
+        rescue Ace::Git::ProviderUnknownOutcomeError => e
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "#{e.message}; reconcile by exact identity before repeating: #{identity}"
+        end
+
+        # Server-derived draft state must agree with the request for an
+        # existing exact match to be reusable.
+        def ensure_draft_agreement!(existing, draft)
+          return if existing.draft == draft
+
+          raise Ace::Git::ProviderConflictingMatchesError,
+            "Open pull request ##{existing.number} matches the exact identity but reports " \
+            "draft #{existing.draft.inspect} while draft #{draft.inspect} was requested"
+        end
+
+        # The read-back of an accepted create must prove the requested draft
+        # state; anything else is a contradictory outcome, never a receipt.
+        def ensure_draft_outcome!(created, draft)
+          return if created.draft == draft
+
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "PR ##{created.number} was created but reports draft #{created.draft.inspect} " \
+            "while draft #{draft.inspect} was requested; reconcile before repeating"
+        end
+
+        # Forgejo derives draft state from WIP title prefixes (server
+        # defaults, compared case-insensitively without trimming); the API
+        # create form has no draft field.
+        def draft_title!(title, draft)
+          if draft
+            work_in_progress_title?(title) ? title : "WIP: #{title}"
+          elsif work_in_progress_title?(title)
+            raise Ace::Git::ProviderConflictingMatchesError,
+              "Requested draft:false conflicts with the WIP-prefixed title #{title.inspect}; " \
+              "Forgejo would create the pull request as a draft"
+          else
+            title
+          end
+        end
+
+        def work_in_progress_title?(title)
+          WIP_PREFIXES.any? { |prefix| title.to_s.upcase.start_with?(prefix) }
+        end
+
+        # Remove one leading WIP prefix for the ready transition. A draft
+        # whose title carries none of the known prefixes means the server
+        # uses configured prefixes this provider cannot strip: refusing
+        # before the mutation keeps the draft state truthful.
+        def strip_wip_prefix!(title, number)
+          prefix = WIP_PREFIXES.find { |candidate| title.to_s.upcase.start_with?(candidate) }
+          unless prefix
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "PR ##{number} reports draft but its title carries no known WIP prefix " \
+              "(#{WIP_PREFIXES.join(", ")}); the server likely uses configured prefixes " \
+              "this provider cannot strip safely"
+          end
+          title.to_s.slice(prefix.length..).to_s.sub(/\A +/, "")
+        end
+
+        # Same-server fork heads ride the documented "owner:branch" API
+        # form. The declared source must resolve to the selected host with
+        # an owner path; cross-host sources are refused before any
+        # mutation (the exact-match lookup may read first).
+        def api_head_argument!(head_repository_url, head_ref)
+          return head_ref if head_repository_url.nil? ||
+            Ace::Git::Atoms::ServerUrl.match?(head_repository_url, server.url)
+          unless same_server_authority?(head_repository_url)
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "PR create cannot target head repository #{head_repository_url} outside the " \
+              "selected server #{server.url}; only canonical and same-server fork sources are supported"
+          end
+
+          owner = URI.parse(head_repository_url.to_s).path.to_s.split("/").reject(&:empty?).first
+          unless owner
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "Head repository #{head_repository_url.inspect} has no owner path; " \
+              "cannot encode the fork head for #{server.url}"
+          end
+          "#{owner}:#{head_ref}"
+        end
+
+        def same_server_authority?(url)
+          authority = Ace::Git::Atoms::ServerUrl.normalize(url).split("/", 2).first.to_s
+          !authority.empty? && authority == selected_server_authority
+        end
+
+        def selected_server_authority
+          @selected_server_authority ||= Ace::Git::Atoms::ServerUrl.normalize(server.url).split("/", 2).first.to_s
+        end
+
+        # Head repository URL provenance from an API payload: canonical
+        # pulls carry the selected repository; fork pulls carry their own;
+        # a deleted fork repository reports none, and that absence stays
+        # honest instead of being relabelled.
+        def api_head_repository_url(payload)
+          full_name = payload.dig("head", "repo", "full_name")
+          return nil if !full_name.is_a?(String) || full_name.empty?
+
+          "#{server_host_root}/#{full_name}"
+        end
+
+        # Authoritative API evidence for one pull request. The base
+        # repository must be the selected one: a misrouted payload is never
+        # relabelled.
+        def normalize_api_pr(payload)
+          base_full_name = payload.dig("base", "repo", "full_name").to_s
+          unless !base_full_name.empty? && base_full_name.casecmp(repository_target.repo).zero?
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "Forgejo returned pull request ##{payload["number"]} with base repository " \
+              "#{base_full_name.inspect} for selected #{repository_target.repo}; refusing misrouted evidence"
+          end
+          state = if payload["state"] == "open"
+            :open
+          elsif payload["merged"] == true
+            :merged
+          else
+            :closed
+          end
+          merge_commit = payload["merge_commit_sha"]
+          Ace::Git::ProviderPullRequest.new(
+            server_name: server.name,
+            number: payload["number"],
+            title: payload["title"],
+            body: payload["body"].is_a?(String) ? payload["body"] : nil,
+            state: state,
+            head_ref: payload.dig("head", "ref"),
+            base_ref: payload.dig("base", "ref"),
+            head_sha: payload.dig("head", "sha"),
+            author: payload.dig("user", "login"),
+            url: pr_url(payload["number"]),
+            draft: payload["draft"],
+            merged_at: payload["merged_at"].is_a?(String) ? payload["merged_at"] : nil,
+            head_repository_url: api_head_repository_url(payload),
+            base_repository_url: repository_target.url,
+            merge_commit_sha: merge_commit.is_a?(String) && !merge_commit.empty? ? merge_commit : nil
+          )
+        end
+
+        # A merge receipt requires authoritative merged evidence: the merged
+        # state, the merge commit, and the exact source SHA that was merged.
+        def prove_merged!(pull_request, expected_head)
+          return if pull_request.state == :merged && pull_request.head_sha == expected_head &&
+            pull_request.merge_commit_sha.to_s.match?(/\A[0-9a-f]{40}\z/)
+
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "Merge accepted but PR ##{pull_request.number} does not prove merged state at " \
+            "#{expected_head} with a merge commit on #{server.name}; reconcile before repeating"
+        end
+
+        # A merge refusal that is not the stale-head case: reconcile by read
+        # before deciding — an authoritative already-merged result at the
+        # expected source SHA is reusable; a closed-unmerged pull request is
+        # a classified refusal; everything else stays an unknown outcome.
+        def reconcile_refused_merge(number, expected_head, outcome)
+          after = verify_post_mutation_head!(number, expected_head, "merge reconciliation")
+          if after.state == :merged && after.head_sha == expected_head &&
+              after.merge_commit_sha.to_s.match?(/\A[0-9a-f]{40}\z/)
+            return receipt(:merge, after, nil)
+          end
+          if after.state == :closed
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "PR ##{number} is closed without merge; Forgejo refused the merge " \
+              "(HTTP #{outcome.status}: #{outcome.message})"
+          end
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "Merge outcome unknown for #{server.name}/##{number}, head #{expected_head}: " \
+            "server returned HTTP #{outcome.status} (#{outcome.message}) and the read-back does not " \
+            "prove a merge; reconcile before repeating"
+        end
+
+        # A duplicate-create race: the exact match is the authoritative
+        # winner of the concurrent create.
+        def reconcile_raced_create(head_repository_url:, head_ref:, base_ref:, expected_head:, draft:)
+          matches = find_open_pull_requests(
+            head_repository_url: head_repository_url, head_ref: head_ref,
+            base_repository_url: server.url, base_ref: base_ref
+          )
+          if matches.size == 1
+            existing = verify_expected_head!(matches.first, expected_head)
+            ensure_draft_agreement!(existing, draft)
+            return receipt(:create, existing, :existing)
+          end
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "PR create refused as duplicate but #{matches.size} open pull requests match " \
+            "#{identity_text(head_repository_url, head_ref, base_ref)}; reconcile by exact identity before repeating"
+        end
+
+        # A refused create (404/422) mutated nothing: classify the server's
+        # own explanation instead of racing a retry.
+        def classify_create_refusal(outcome, head_repository_url, head_ref, base_ref)
+          error = outcome.status == 404 ? Ace::Git::ProviderObjectNotFoundError : Ace::Git::ProviderIdentityMismatchError
+          raise error,
+            "Forgejo refused the create of #{identity_text(head_repository_url, head_ref, base_ref)} " \
+            "(HTTP #{outcome.status}: #{outcome.message})"
+        end
+
+        def pr_api
+          @pr_api ||= PullRequestApi.new(server: server, timeout: timeout, runner: runner)
+        end
+
         def require_open_pr!(pr)
           return if pr.state == :open
 
@@ -533,24 +856,25 @@ module Ace
           @review_http ||= HttpClient.new(server: server, timeout: timeout, runner: runner)
         end
 
-  # A mutation receipt may only bind the expected head; if the PR head
-  # moved during the mutation the outcome stays uncertain.
-  def verify_post_mutation_head!(number, expected_head, correlation)
-    current = begin
-      pull_request(number: number)
-    rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
-      raise Ace::Git::ProviderUnknownOutcomeError,
-        "Head verification read failed after mutation for #{server.name}: #{e.message}; reconcile before repeating"
-    end
-    return if current.head_sha == expected_head
+        # A mutation receipt may only bind the expected head; if the PR head
+        # moved during the mutation the outcome stays uncertain. Returns the
+        # authoritative read-back when the head still matches.
+        def verify_post_mutation_head!(number, expected_head, correlation)
+          current = begin
+            pull_request(number: number)
+          rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
+            raise Ace::Git::ProviderUnknownOutcomeError,
+              "Head verification read failed after mutation for #{server.name}: #{e.message}; reconcile before repeating"
+          end
+          return current if current.head_sha == expected_head
 
-    raise Ace::Git::ProviderUnknownOutcomeError,
-      "PR head moved during mutation for #{server.name}/##{number} " \
-      "(#{expected_head} -> #{current.head_sha}), session #{correlation}: reconcile before repeating"
-  end
+          raise Ace::Git::ProviderUnknownOutcomeError,
+            "PR head moved during mutation for #{server.name}/##{number} " \
+            "(#{expected_head} -> #{current.head_sha}), session #{correlation}: reconcile before repeating"
+        end
 
         # Serialize the read/post/reconcile sequence per session so two
-      # concurrent callers cannot both observe "no marker" and post.
+        # concurrent callers cannot both observe "no marker" and post.
         def with_session_lock(correlation)
           require "tmpdir"
           lock_path = File.join(Dir.tmpdir, "ace-review-session-#{correlation}.lock")
@@ -567,18 +891,18 @@ module Ace
           "<!-- ace-review-session:#{correlation} -->"
         end
 
-        def matching_review_comments(number, marker, expected_head)
+        def matching_review_comments(number, marker)
           review_http.paginate("issues/#{number}/comments").filter_map do |entry|
             unless entry.is_a?(Hash) && entry["body"].is_a?(String)
               raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR comment collection"
             end
             next unless entry["body"].include?(marker)
 
-            review_comment(entry, number, expected_head)
+            review_comment(entry, number)
           end
         end
 
-        def review_comment(entry, number, head)
+        def review_comment(entry, number)
           user = entry.is_a?(Hash) ? entry["user"] : nil
           unless entry.is_a?(Hash) && entry["id"].is_a?(Integer) && entry["id"].positive? && entry["body"].is_a?(String) &&
               user.is_a?(Hash) && user["login"].is_a?(String)
@@ -675,23 +999,7 @@ module Ace
           classify_failure(result[:stderr], context: operation_context(operation, arguments))
         end
 
-        # Send one mutating repository operation. When `ambiguous` is true
-        # (create), any transport-level failure becomes an unknown outcome:
-        # the request may have mutated the forge, so callers must reconcile
-        # by exact identity instead of retrying blindly.
-        def send_mutation(operation, *arguments, ambiguous:, identity: nil)
-          result = execute_repository(operation, arguments)
-          return result if result[:success]
-
-          classify_failure(result[:stderr], context: operation_context(operation, arguments))
-        rescue Ace::Git::ProviderUnreachableError => e
-          raise e unless ambiguous
-
-          raise Ace::Git::ProviderUnknownOutcomeError,
-            "PR create outcome unknown after transport failure (#{e.message}); " \
-            "reconcile by exact identity before repeating: #{identity}"
-        end
-
+        # Run one repository-scoped `fj` operation on the validated target.
         def execute_repository(operation, arguments)
           target = repository_target
           ensure_observed_version!
@@ -728,17 +1036,6 @@ module Ace
           end
         end
 
-        # Fetch one PR as normalized evidence with exact head SHA.
-        def fetch_pr(number)
-          with_head_sha(view_pr(number))
-        end
-
-        # Complete a parsed PR view with its exact head SHA evidence.
-        def with_head_sha(parsed)
-          parsed[:head_sha] = head_sha_of(parsed[:number])
-          normalize_pr(parsed)
-        end
-
         # View one PR and parse its stable minimal-style output. The
         # qualified `owner/repo#N` reference binds the read to the selected
         # repository; a returned number that disagrees with the request is a
@@ -752,27 +1049,6 @@ module Ace
           parsed
         end
 
-        # Re-fetch and verify the PR created by an accepted create request.
-        def reconcile_created(head_repository_url:, head_ref:, base_ref:, expected_head:)
-          matches = find_open_pull_requests(
-            head_repository_url: head_repository_url, head_ref: head_ref,
-            base_repository_url: server.url, base_ref: base_ref
-          )
-          if matches.empty?
-            raise Ace::Git::ProviderUnknownOutcomeError,
-              "PR create accepted but no open pull request matches " \
-              "#{head_repository_url}@#{head_ref} -> #{server.url}@#{base_ref}; " \
-              "reconcile by exact identity before repeating"
-          end
-          if matches.size > 1
-            raise Ace::Git::ProviderConflictingMatchesError,
-              "Multiple open pull requests match #{head_repository_url}@#{head_ref} -> " \
-              "#{base_ref}: #{matches.map(&:number).join(", ")}; resolve the conflict first"
-          end
-
-          verify_expected_head!(matches.first, expected_head)
-        end
-
         def require_base_on_server!(base_repository_url)
           return if Ace::Git::Atoms::ServerUrl.match?(base_repository_url, server.url)
 

data/lib/ace/git/forgejo/pull_request_api.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Git
+    module Forgejo
+      # Repository-bound Forgejo API v1 operations for the PR delivery
+      # lifecycle (create, edit, ready, merge) plus the authoritative single
+      # pull request read.
+      #
+      # The fj v0.6 CLI cannot encode a fork head, an explicit draft state,
+      # a ready transition, or an atomic expected-head merge precondition;
+      # this molecule owns those endpoints on the same selected host and
+      # token transport as {HttpClient}. Every returned payload is validated
+      # against the documented Forgejo `PullRequest` schema before it may
+      # become provider evidence; contradictory or missing identity fields
+      # fail closed as malformed evidence.
+      #
+      # Mutations return a {MutationOutcome} for the statuses that carry
+      # endpoint-specific meaning (201/200 success, 405/409/422 refusal) so
+      # the provider can classify the forge's own semantics; authentication,
+      # absence, and transport failures raise the shared taxonomy directly.
+      class PullRequestApi
+        # Official capability evidence (see the task capability-evidence
+        # report): `head_commit_id` merge enforcement is documented from
+        # release branch v7.0, and the API `draft` field is only computed
+        # from the WIP title from v8.0 (`Draft: pr.IsWorkInProgress` and a
+        # non-omitempty bool; v7.0 leaves it unset). The lifecycle proves
+        # draft state, so the floor is the first line reporting both.
+        MINIMUM_SERVER_VERSION = Gem::Version.new("8.0.0")
+
+        # Outcome of one mutation send whose status the provider must
+        # interpret: the HTTP status, the sanitized server message (nil on
+        # success), and the parsed payload when the server returned one.
+        MutationOutcome = Data.define(:status, :message, :payload)
+
+        def initialize(server:, timeout:, runner: nil)
+          @http = HttpClient.new(server: server, timeout: timeout, runner: runner)
+        end
+
+        # Probe and validate the selected server's API version once per
+        # instance. Every lifecycle mutation gate goes through here and
+        # fails closed when the server cannot prove the documented
+        # capability floor. Transport and authentication failures classify
+        # as they would for any read; an unusable or too-old version
+        # reports is a capability refusal.
+        #
+        # @raise [Ace::Git::ProviderUnsupportedCapabilityError] when the
+        #   server version cannot be verified or is below the floor
+        def ensure_version_supported!
+          return if @version_supported
+
+          status, payload = @http.exchange(:get, "/api/v1/version")
+          version_text = payload.is_a?(Hash) ? payload["version"] : nil
+          unless status == 200 && version_text.is_a?(String) && !version_text.empty?
+            if [401, 403].include?(status.to_i)
+              raise Ace::Git::ProviderAuthenticationError,
+                "Forgejo server version probe returned HTTP #{status}; authenticate with fj first"
+            end
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Forgejo server did not report a usable API version (HTTP #{status}); " \
+              "cannot prove the PR delivery capability floor " \
+              "#{MINIMUM_SERVER_VERSION} before mutating"
+          end
+
+          version = parse_version(version_text)
+          unless version >= MINIMUM_SERVER_VERSION
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Forgejo server reports #{version}; PR delivery requires #{MINIMUM_SERVER_VERSION} " \
+              "(server-enforced expected-head merge is not documented below it)"
+          end
+          @version_supported = true
+        end
+
+        # @return [Hash] the raw validated pull request payload
+        # @raise [Ace::Git::ProviderObjectNotFoundError] when absent
+        # @raise [Ace::Git::ProviderMalformedOutputError] on schema violation
+        # @raise [Ace::Git::ProviderIdentityMismatchError] when the payload
+        #   reports another object number (misrouted evidence)
+        def pull_request(number)
+          status, payload = @http.exchange(:get, "pulls/#{number}")
+          case status
+          when 200 then validate_pr_payload!(payload, number)
+          when 404 then raise Ace::Git::ProviderObjectNotFoundError, "Forgejo pull request ##{number} not found"
+          when 401, 403
+            raise Ace::Git::ProviderAuthenticationError,
+              "Forgejo pull request ##{number} read failed with HTTP #{status}"
+          else
+            raise Ace::Git::ProviderUnreachableError,
+              "Forgejo pull request ##{number} read failed with HTTP #{status}"
+          end
+        end
+
+        # @return [Array<Hash>] validated payloads of all open pull requests
+        def open_pull_requests
+          @http.paginate("pulls?state=open").map { |payload| validate_pr_payload!(payload, payload["number"]) }
+        end
+
+        # Send the create mutation. The head argument must already be in the
+        # documented API form (plain branch, or "owner:branch" for a
+        # same-server fork).
+        #
+        # @return [MutationOutcome] 201 with the created payload, or a
+        #   refusal outcome (409 duplicate, 404/422 unprovable source)
+        def create_pull_request(head:, base:, title:, body: nil)
+          form = {"title" => title, "base" => base, "head" => head}
+          form["body"] = body if body
+          status, payload, message = @http.exchange(:post, "pulls", body: form)
+          classify_send!(status, "create pull request")
+          MutationOutcome.new(status: status, message: message, payload: payload)
+        end
+
+        # Edit title/body of one pull request (also the ready transition:
+        # Forgejo marks a draft ready by removing its WIP title prefix).
+        #
+        # @return [MutationOutcome] 200, or a refusal outcome
+        def edit_pull_request(number, title: nil, body: nil)
+          form = {}
+          form["title"] = title if title
+          form["body"] = body if body
+          status, payload, message = @http.exchange(:patch, "pulls/#{number}", body: form)
+          classify_send!(status, "edit pull request #{number}")
+          MutationOutcome.new(status: status, message: message, payload: payload)
+        end
+
+        # Send the server-enforced merge: Forgejo re-resolves the head ref
+        # at merge time and refuses with 409 when it does not equal
+        # `head_commit_id` (documented `MergePullRequestOption`).
+        #
+        # @param do_method [String] "squash", "merge", or "rebase"
+        # @return [MutationOutcome] 200, or a refusal outcome (405 disabled
+        #   style, 409 stale head / conflicts / already merged)
+        def merge_pull_request(number, do_method:, head_commit_id:)
+          form = {"Do" => do_method, "head_commit_id" => head_commit_id}
+          status, payload, message = @http.exchange(:post, "pulls/#{number}/merge", body: form)
+          classify_send!(status, "merge pull request #{number}")
+          MutationOutcome.new(status: status, message: message, payload: payload)
+        end
+
+        private
+
+        # Authentication, absence, and transport failures classify directly
+        # inside the transport; only statuses whose meaning is
+        # endpoint-specific reach the provider as an outcome.
+        def classify_send!(status, operation)
+          return if (200..299).cover?(status)
+          return if [404, 405, 409, 422].include?(status.to_i)
+
+          error = case status.to_i
+          when 401, 403 then Ace::Git::ProviderAuthenticationError
+          else Ace::Git::ProviderUnknownOutcomeError
+          end
+          raise error, "Forgejo #{operation} returned HTTP #{status}; reconcile before repeating"
+        end
+
+        def validate_pr_payload!(payload, requested_number)
+          unless payload.is_a?(Hash)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo pull request evidence"
+          end
+          head = payload["head"]
+          base = payload["base"]
+          unless payload["number"].is_a?(Integer) && payload["number"].positive? &&
+              %w[open closed].include?(payload["state"]) &&
+              [true, false].include?(payload["draft"]) &&
+              [true, false].include?(payload["merged"]) &&
+              head.is_a?(Hash) && head["ref"].is_a?(String) && !head["ref"].empty? &&
+              head["sha"].to_s.match?(/\A[0-9a-f]{40}\z/) &&
+              base.is_a?(Hash) && base["ref"].is_a?(String) && !base["ref"].empty?
+            raise Ace::Git::ProviderMalformedOutputError,
+              "Malformed Forgejo pull request payload (missing number/state/draft/head/base identity)"
+          end
+          unless payload["number"] == requested_number
+            raise Ace::Git::ProviderIdentityMismatchError,
+              "Forgejo returned pull request ##{payload["number"]} for selected ##{requested_number}; " \
+              "refusing misrouted evidence"
+          end
+          payload
+        end
+
+        # Server version strings look like "7.0.5+gitea-..." or "v12.0.1";
+        # only the leading numeric release is comparable.
+        def parse_version(text)
+          match = text.strip.sub(/\Av/i, "").match(/\A(\d+\.\d+\.\d+)/)
+          unless match
+            raise Ace::Git::ProviderUnsupportedCapabilityError,
+              "Forgejo server version #{text.inspect} is not a comparable release; " \
+              "cannot prove the PR delivery capability floor #{MINIMUM_SERVER_VERSION}"
+          end
+          Gem::Version.new(match[1])
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/forgejo/repository_binding.rb

@@ -100,17 +100,6 @@ module Ace
           pr_search: ->(target, state) do
             ["--style", "minimal", "pr", "search", "--state", state, "-r", target.repo]
           end,
-          pr_create: ->(target, title, head_ref, base_ref, body) do
-            argv = ["pr", "create", title, "--head", head_ref, "--base", base_ref]
-            argv += ["--body", body] if body
-            argv + ["-r", target.repo]
-          end,
-          pr_edit_title: ->(target, number, title) do
-            ["pr", "edit", target.qualified_ref(number), "title", title]
-          end,
-          pr_edit_body: ->(target, number, body) do
-            ["pr", "edit", target.qualified_ref(number), "body", body]
-          end,
           issue_view: ->(target, number) do
             ["--style", "minimal", "issue", "view", target.qualified_ref(number)]
           end,

data/lib/ace/git/forgejo/version.rb

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Forgejo
-      VERSION = "0.5.0"
+      VERSION = "0.6.0"
     end
   end
 end

data/lib/ace/git/forgejo.rb

@@ -8,6 +8,7 @@ require_relative "forgejo/cli_executor"
 require_relative "forgejo/pr_identifier"
 require_relative "forgejo/parsers"
 require_relative "forgejo/http_client"
+require_relative "forgejo/pull_request_api"
 require_relative "forgejo/provider"
 
 module Ace

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git-forgejo
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-git
@@ -23,6 +23,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.26'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 description: 'Implements the shared ace-git provider contract for Forgejo: all `fj`
   CLI invocation, output parsing, authentication verification, and classified failure
   handling live behind one normalized evidence boundary. Ad-hoc curl fallbacks are
@@ -44,6 +72,7 @@ files:
 - lib/ace/git/forgejo/parsers.rb
 - lib/ace/git/forgejo/pr_identifier.rb
 - lib/ace/git/forgejo/provider.rb
+- lib/ace/git/forgejo/pull_request_api.rb
 - lib/ace/git/forgejo/repository_binding.rb
 - lib/ace/git/forgejo/version.rb
 homepage: https://forgejo.tail6c0887.ts.net/cs3b/ace