ace-git-forgejo 0.4.0 → 0.6.0

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

@@ -2,24 +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"
@@ -47,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
@@ -109,13 +127,94 @@ module Ace
           )
         end
 
+        def issue_tracking(number:)
+          data = issue_api.issue(request_number!(number))
+          unless data.is_a?(Hash) && data["number"].to_i == number.to_i &&
+              data["html_url"].to_s == issue_url(number.to_i)
+            raise Ace::Git::ProviderIdentityMismatchError, "Issue ##{number} is not in #{server.url}"
+          end
+          evidence = Ace::Git::ProviderIssue.new(
+            server_name: server.name, number: data["number"], title: data["title"],
+            state: normalize_state(data["state"]),
+            author: data.dig("user", "login"), url: data["html_url"],
+            labels: Array(data["labels"]).map { |label| label["name"] }
+          )
+          {issue: evidence,
+           comments: Array(issue_api.comments(number)).map { |c| {id: c.fetch("id"), body: c["body"].to_s} },
+           labels: evidence.labels}
+        end
+
+        # Unrecognized or missing state is malformed evidence: mapping it to
+        # :closed would let sync close an issue without valid state proof.
+        def normalize_state(value)
+          case value.to_s
+          when "open" then :open
+          when "closed" then :closed
+          else raise Ace::Git::ProviderMalformedOutputError, "Unknown issue state #{value.inspect}"
+          end
+        end
+
+        def create_issue_comment(number:, body:)
+          issue_api.create_comment(request_number!(number), body)
+        end
+
+        def update_issue_comment(number:, comment_id:, body:)
+          assert_issue_comment_owned!(number, comment_id)
+          issue_api.update_comment(Integer(comment_id), body)
+        end
+
+        def delete_issue_comment(number:, comment_id:)
+          assert_issue_comment_owned!(number, comment_id)
+          issue_api.delete_comment(Integer(comment_id))
+        end
+
+        def add_issue_label(number:, label:)
+          issue_api.add_label(request_number!(number), ensure_repo_label_id(label))
+        end
+
+        def remove_issue_label(number:, label:)
+          match = Array(issue_api.repository_labels(wanted: label)).find { |entry| entry["name"] == label }
+          return unless match
+
+          issue_api.remove_label(request_number!(number), match.fetch("id"))
+        end
+
+        # Fresh repositories lack the tracking label; creating it on demand
+        # keeps issue linking from committing a tracking comment it could
+        # never label. A concurrent creator surfaces as an uncertain mutation
+        # outcome, which only means re-list and attach what appeared.
+        def ensure_repo_label_id(label)
+          match = Array(issue_api.repository_labels(wanted: label)).find { |entry| entry["name"] == label }
+          return match["id"] if match && match["id"].to_i.positive?
+
+          begin
+            issue_api.create_repo_label(name: label, color: TRACKED_LABEL_COLOR)
+          rescue Ace::Git::ProviderUnknownOutcomeError
+            nil
+          end
+          match = Array(issue_api.repository_labels(wanted: label)).find { |entry| entry["name"] == label }
+          unless match && match["id"].to_i.positive?
+            raise Ace::Git::ProviderObjectNotFoundError,
+              "Forgejo label #{label.inspect} could not be created or found on #{server.url}"
+          end
+          match["id"]
+        end
+
+        def set_issue_state(number:, state:)
+          raise ArgumentError, "Invalid issue state #{state.inspect}" unless %i[open closed].include?(state)
+
+          issue_api.set_state(request_number!(number), state)
+        end
+
         # @return [Array<ProviderCheck>] normalized check evidence for a ref
         def checks(ref:)
           tasks = fj(:actions_tasks)
           Parsers.parse_actions_tasks(tasks)
-            # Exact-head evidence requires the complete 40-character SHA
-            # equal to the reviewed head; prefix matches are rejected.
-            .select { |task| task[:sha] == ref.to_s }
+            # Exact-head evidence binds each task to the reviewed head by SHA
+            # prefix: a full or abbreviated SHA that prefixes the reviewed
+            # head identifies that commit, and anything else is another
+            # head's task. No matching evidence is silently dropped.
+            .select { |task| ref.to_s.downcase.start_with?(task[:sha].downcase) }
             .map do |task|
               Ace::Git::ProviderCheck.new(
                 server_name: server.name,
@@ -125,6 +224,13 @@ module Ace
                 url: nil
               )
             end
+        rescue Ace::Git::ProviderObjectNotFoundError
+          # A repository with Actions disabled serves no tasks endpoint. The
+          # review flows resolve the repository binding and the PR before
+          # collecting checks, so a not-found here means CI is unavailable,
+          # not a missing repository; empty check evidence keeps the review
+          # collectable. Parse and transport failures still fail closed.
+          []
         end
 
         # @return [ProviderRepository] normalized repository evidence
@@ -160,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)
@@ -174,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(
@@ -230,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}"
@@ -260,8 +366,8 @@ module Ace
               "session #{correlation}: #{e.message}; reconcile before repeating"
           end
           begin
-          matches = matching_review_comments(number, marker, expected_head)
-          rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderUnreachableError => e
+          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"
           end
@@ -293,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)
@@ -314,7 +420,7 @@ module Ace
             # Fetch individually and validate the Forgejo issue identity.
             begin
               updated = review_http.request(:get, update_route)
-            rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderUnreachableError => e
+            rescue Ace::Git::ProviderMalformedOutputError, Ace::Git::ProviderAuthenticationError, Ace::Git::ProviderObjectNotFoundError, Ace::Git::ProviderUnreachableError => e
               raise Ace::Git::ProviderUnknownOutcomeError,
                 "Comment update sent but verification read failed for comment #{comment_id}: #{e.message}; reconcile before repeating"
             end
@@ -331,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:)
@@ -340,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
@@ -383,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
 
@@ -441,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::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")
@@ -475,27 +891,31 @@ 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|
-            next unless entry.is_a?(Hash) && entry["body"].is_a?(String) && entry["body"].include?(marker)
+            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) &&
-              entry.dig("user", "login").is_a?(String)
+              user.is_a?(Hash) && user["login"].is_a?(String)
             raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR comment evidence"
           end
           Ace::Git::ProviderReviewComment.new(
             server_name: server.name, repository_url: server.url, pr_number: number,
-            id: entry["id"], author: entry.dig("user", "login"), body: entry["body"],
+            id: entry["id"], author: user["login"], body: entry["body"],
             url: entry["html_url"], path: entry["path"],
             # Forgejo supplies position/original_position rather than
             # line; the positive side position is the normalized line.
             line: entry["line"] || [entry["position"], entry["original_position"]].compact.reject { |v| !v.is_a?(Integer) || v <= 0 }.first,
-            head_sha: entry["commit_id"] || head, resolved: entry.key?("resolver") ? !entry["resolver"].nil? : nil,
+            head_sha: entry["commit_id"], resolved: entry.key?("resolver") ? !entry["resolver"].nil? : nil,
             thread_id: nil
           )
         end
@@ -512,18 +932,28 @@ module Ace
         end
 
         def review_entry(entry, number, head)
-          reviewer = entry.dig("user", "login") || entry.dig("team", "name")
-          unless entry.is_a?(Hash) && entry["id"].is_a?(Integer) && entry["id"].positive? && reviewer.is_a?(String) &&
+          unless entry.is_a?(Hash)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR review evidence"
+          end
+          user, team = entry["user"], entry["team"]
+          unless user.nil? || user.is_a?(Hash)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR review evidence: user must be an object"
+          end
+          unless team.nil? || team.is_a?(Hash)
+            raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR review evidence: team must be an object"
+          end
+          reviewer = user&.[]("login") || team&.[]("name")
+          unless entry["id"].is_a?(Integer) && entry["id"].positive? && reviewer.is_a?(String) &&
               entry["state"].is_a?(String) && !entry["state"].empty?
             raise Ace::Git::ProviderMalformedOutputError, "Malformed Forgejo PR review evidence"
           end
           Ace::Git::ProviderReview.new(
             server_name: server.name, repository_url: server.url, pr_number: number,
-            id: entry["id"], author: entry.dig("user", "login"), body: entry["body"],
+            id: entry["id"], author: reviewer, body: entry["body"],
             # Forgejo reports REQUEST_CHANGES; consumers count only the
             # canonical CHANGES_REQUESTED spelling.
             state: (entry["state"] == "REQUEST_CHANGES") ? "CHANGES_REQUESTED" : entry["state"],
-            url: entry["html_url"], head_sha: entry["commit_id"] || head
+            url: entry["html_url"], head_sha: entry["commit_id"]
           )
         end
 
@@ -534,6 +964,17 @@ module Ace
           )
         end
 
+        def assert_issue_comment_owned!(number, comment_id)
+          return if issue_tracking(number: number)[:comments].any? { |comment| comment[:id].to_i == comment_id.to_i }
+
+          raise Ace::Git::ProviderIdentityMismatchError,
+            "Comment #{comment_id} is not on selected issue ##{number} in #{server.url}"
+        end
+
+        def issue_api
+          @issue_api ||= IssueApi.new(server: server, timeout: timeout, runner: runner)
+        end
+
         # Validated selected repository identity. Built once; malformed
         # selections fail as configuration errors before any subprocess.
         def repository_target
@@ -558,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!
@@ -611,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
@@ -635,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)
 
@@ -788,8 +1181,9 @@ module Ace
         end
 
         def issue_url(number)
-          base = repository_target.url.to_s.chomp("/")
-          "#{base}/issues/#{number}"
+          # Identity evidence comes from the web endpoint, not the clone URL
+          # (which may be SSH-style and is not a parseable web URL).
+          "#{Ace::Git::Atoms::ServerUrl.web_base(server.url)}/issues/#{number}"
         end
       end
     end