ace-git 0.30.1 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c03430c6a212d4bb6c51a3cb4bbf8f884051fe37b55581f9ea3d5d14048c83fa
-  data.tar.gz: e4da9c0fc2ae249ff7459973be3bfa42679395a68cb184e49446ea049aa5074f
+  metadata.gz: 83d5b624eab98d754e4bb770fdd1a80e00237d063bc07ba2b412e31cf0b4fa87
+  data.tar.gz: 1e8a556aedb3f9ba844ebe46a7b3c64adea58b979842bf6df7835742057c20c1
 SHA512:
-  metadata.gz: 60ade30b905d89e860b44636d5520f7b5365612cbf4182692c3c06ca73a157b0d5811b4a3a8710a6b382180276ec4c8d488c4a156833af455d4baebcfd8a7797
-  data.tar.gz: e3dbbf14e495ac5bc6389079dd62d4c04a19f59ef4bc7d8d4a04507a63af5e52bc4ed734cadea17d6824d1cde353002bd4717bc9b4270282a670d42b72340983
+  metadata.gz: 8c33109eb792dea197dc9e29a9f63839ed10d53c95aa7e1817d22cbbe2cbecc51123f8fe90ad420a2e908b35a6aa1bbaef35612340bcd667ad21b5736dbdad49
+  data.tar.gz: a2b337d9084ff29b01cd0834e2e9e9a3ef36299d0c0704bdad61480d844cd1a0165f1d4b9c482c5acf0feb29d0dc6aaa715e992dca1e2fa50d6abeb736e234f7

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-10-23
+
+### Added
+
+- Formal reviewer-owned, exact-head provider approval and read-only approval verification through the forge-neutral review flow; comments do not substitute for approval.
+
+
+### Fixed
+
+- Serialize all local review correlations per normalized PR, validate selected/relevant review actors without rejecting unrelated historical comments, and preserve unsafe pending reviews with explicit refusal.
+
 ## [0.30.1] - 2026-10-17
 
 ### Changed

data/docs/usage.md

@@ -330,3 +330,66 @@ Configure servers in `.ace/git/config.yml` under `git.servers`, then
 resolve them by name, by default, or from a git remote URL. Every failure path is
 classified (missing CLI, unauthenticated, unreachable, malformed output, object
 not found) with no silent fallbacks.
+
+
+### Formal provider approval
+
+```sh
+ace-git pr approve 25 --expected-head FULL_SHA --body-file accepted-review.md --correlation review-123 --server forge --format json
+ace-git pr approval 25 --expected-head FULL_SHA --review-id 99 --server forge --format json
+```
+
+`approve` publishes an already accepted independent review under the configured
+provider identity; it does not invoke a model or decide the review verdict. The
+UTF-8 report must be nonempty, contain no reserved approval marker, and fit in
+64KiB. The PR must be open, ready and at the full lowercase expected SHA; its
+author cannot approve it. GitHub and Forgejo return a verified effective formal
+approval, including exact repository/PR/head, reviewer ID/login, review ID/URL,
+evidence SHA256, correlation, and `created|existing`. Forgejo additionally checks
+official review status. A comment or `pr ready` is a separate operation.
+
+`approval` is read-only and verifies the current effective approval identified by
+the numeric provider review ID. Integrators compare its receipt with the accepted
+reviewer artifact; they do not mint a substitute review. Existing server selection
+and JSON error categories apply. Role instructions confer no provider permission;
+credentials remain with the deployment-configured account.
+
+Correlation is scoped to the selected provider/server/repository/PR. Reusing it
+with changed visible evidence conflicts. A same-account local per-PR flock serializes all correlations/worktrees
+for concurrent publication; this is not a distributed uniqueness service. Provider
+visibility may hide another account's pending reviews, and separate hosts do not
+share this lock. No success is inferred for invisible evidence. Save the receipt
+in the existing review/assignment artifacts; there is no new journal.
+
+After an unknown direct-create outcome, explicitly resume the same publication
+to reconcile provider state first. Mutations are never automatically retried.
+Changed head, stale/dismissed/nonofficial approval, unavailable evidence or
+unsupported capability withholds success rather than using a comment, another
+identity, or weaker branch protection. Actual provider/account acceptance remains
+a separate deployment proof from deterministic package tests.
+
+
+Formal approval requires a **dedicated automation reviewer identity and one
+writer per actor/repository/PR**, supplied by deployment. All local correlations
+share a private per-PR lock in the system temporary directory, independently of
+worktree/TMPDIR. Another host or manual client sharing that identity violates
+the supported execution contract: neither provider offers a pending-review CAS
+through this path. This precondition must be verified before live use; role
+instructions and topology discovery do not establish it.
+
+Both adapters directly create approval with the accepted full commit ID.
+Forgejo 11+ preserves that explicit ID; its pending-submit route instead rebinds
+to current HEAD and is never used. Direct create can reuse pending, so visible
+unrelated pending refuses before mutation. A matching, comment-free own pending
+can resume through Forgejo's verified direct-create path. Pending with comments
+or an unverified safe recovery path (including current GitHub pending recovery)
+is retained with an explicit refusal. Lost direct-create replies reconcile the
+submitted review, without a second automatic POST. No claim of server-atomic
+pending isolation or cross-host mutual exclusion is made.
+
+GitHub actor proof uses authenticated GraphQL viewer login/databaseId under the
+same configured PAT, App user or App installation token. REST `/user` is not
+used for installation credentials. Unavailable/unverifiable viewer or integration
+access refusal is a truthful capability/authentication failure before approval,
+never a guessed bot identity, borrowed token or apparent network outage. Live
+App/account/public-review proof remains separate from deterministic fixtures.

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

@@ -204,6 +204,38 @@ module Ace
             end
           end
 
+          class Approve < BaseCommand
+            desc "Publish a formal approval under the configured reviewer identity"
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact accepted head SHA"
+            option :body_file, type: :string, required: true, desc: "Accepted review report file"
+            option :correlation, type: :string, required: true, desc: "Stable approval publication identity"
+
+            def call(identifier:, expected_head:, body_file:, correlation:, **options)
+              result = lifecycle(options).approve(identifier, expected_head: expected_head,
+                body_file: body_file, correlation: correlation)
+              render_evidence(options, header: "Formal approval confirmed", **result.to_h)
+            rescue Ace::Git::Error, ArgumentError => e
+              render_failure(options, e)
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+
+          class Approval < BaseCommand
+            desc "Read and verify an effective exact-head approval without mutation"
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact accepted head SHA"
+            option :review_id, type: :integer, required: true, desc: "Review ID from the approval receipt"
+
+            def call(identifier:, expected_head:, review_id:, **options)
+              result = lifecycle(options).approval(identifier, expected_head: expected_head, review_id: review_id)
+              render_evidence(options, header: "Formal approval verified", **result.to_h)
+            rescue Ace::Git::Error, ArgumentError => e
+              render_failure(options, e)
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+
           # `ace-git pr merge ID --expected-head SHA --method squash|merge|rebase`
           class Merge < BaseCommand
             desc "Merge with provider-side expected-head enforcement; no default method"

data/lib/ace/git/cli.rb

@@ -53,7 +53,7 @@ module Ace
         ["diff", "Show filtered git diff output"],
         ["status", "Show repository status and PR context"],
         ["branch", "Show current branch information"],
-        ["pr", "Forge-neutral pull request lifecycle: show, create, update, ready, merge"],
+        ["pr", "Forge-neutral pull request lifecycle: show, create, update, ready, approve, approval, merge"],
         ["service merge", "Fixed receiver-owned exact-head merge envelope"],
         ["service create", "Fixed receiver-owned draft PR creation"],
         ["service update", "Fixed receiver-owned draft PR update"],
@@ -74,6 +74,8 @@ module Ace
       register "pr create", Commands::Pr::Create.new
       register "pr update", Commands::Pr::Update.new
       register "pr ready", Commands::Pr::Ready.new
+      register "pr approve", Commands::Pr::Approve.new
+      register "pr approval", Commands::Pr::Approval.new
       register "pr merge", Commands::Pr::Merge.new
       register "service merge", Commands::ServiceMerge.new
       %w[create update ready].each do |operation|

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

@@ -142,6 +142,21 @@ module Ace
           )
         end
 
+        def approve(identifier, expected_head:, body_file:, correlation:)
+          body = load_body(body_file, limit: 64 * 1024 + 1)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.approve_pull_request(number: reference.number, expected_head: expected_head,
+            body: body, correlation: correlation)
+        end
+
+        def approval(identifier, expected_head:, review_id:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.pull_request_approval(number: reference.number, expected_head: expected_head,
+            review_id: review_id)
+        end
+
         def post_review_comment(identifier, expected_head:, body:, correlation:)
           reference = parse_identifier(identifier)
           provider = provider_for(resolve_server_for(reference))
@@ -344,11 +359,11 @@ module Ace
           Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
         end
 
-        def load_body(path)
+        def load_body(path, limit: nil)
           raise ArgumentError, "--body-file is required" unless path
           raise ArgumentError, "Body file not found: #{path}" unless File.file?(path)
 
-          File.read(path)
+          File.read(path, limit)
         rescue SystemCallError => e
           raise ArgumentError, "Cannot read body file #{path}: #{e.message}"
         end

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

@@ -168,6 +168,16 @@ module Ace
           raise NotImplementedError, "Providers must implement #{self.class}#repository_file"
         end
 
+        # Formal approval is distinct from comments. Unsupported adapters refuse;
+        # they must never project an approval as a comment or switch identity.
+        def approve_pull_request(number:, expected_head:, body:, correlation:)
+          raise ProviderUnsupportedCapabilityError, "Formal approval is unsupported by #{self.class}"
+        end
+
+        def pull_request_approval(number:, expected_head:, review_id:)
+          raise ProviderUnsupportedCapabilityError, "Formal approval evidence is unsupported by #{self.class}"
+        end
+
         # Create a top-level PR comment. `correlation` is a stable session key
         # embedded in the body so a retry can find exactly one prior send.
         # A possible post-send transport failure raises ProviderUnknownOutcomeError.

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

@@ -48,6 +48,13 @@ module Ace
       :idempotency
     )
 
+    # Effective formal review, verified against the current provider state.
+    ProviderApprovalReceipt = Data.define(
+      :provider, :server_name, :repository_url, :pr_number, :pr_url, :head_sha,
+      :reviewer_id, :reviewer, :review_id, :review_url, :state, :effective, :official,
+      :correlation, :evidence_sha256, :idempotency
+    )
+
     # Normalized repository evidence.
     ProviderRepository = Data.define(:server_name, :full_name, :default_branch, :url)
 

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

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "digest"
+require "tmpdir"
+require "etc"
+require_relative "evidence"
+require_relative "../atoms/server_url"
+
+module Ace
+  module Git
+    module Providers
+      # Shared policy for formal review evidence. Provider packages supply the
+      # authenticated I/O ports; no credentials or delivery state live here.
+      class FormalApproval
+        SHA = /\A[0-9a-f]{40}\z/
+        CORRELATION = /\A[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}\z/
+        MARKER = /\n\n<!-- ace-approval:([a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}) sha256:([0-9a-f]{64}) -->\z/
+
+        def initialize(provider:, request:, list:, official: false, pending_reuse: false)
+          @provider, @request, @list, @official = provider, request, list, official
+          @pending_reuse = pending_reuse
+        end
+
+        def approve(number:, expected_head:, body:, correlation:)
+          validate_input!(number, expected_head)
+          unless body.is_a?(String) && body.dup.force_encoding(Encoding::UTF_8).valid_encoding? && !body.strip.empty? &&
+              body.bytesize <= 64 * 1024 && !body.include?("\0") && !body.include?("<!-- ace-approval:") &&
+              correlation.is_a?(String) && correlation.match?(CORRELATION)
+            raise ArgumentError, "Approval requires a nonempty UTF-8 report (maximum 64KiB) and valid correlation"
+          end
+          body = body.dup.force_encoding(Encoding::UTF_8)
+          digest = Digest::SHA256.hexdigest(body)
+          sent_body = "#{body}\n\n<!-- ace-approval:#{correlation} sha256:#{digest} -->"
+          # Same existing per-session flock family as comment publication,
+          # with a digest filename so caller text never forms a filesystem path.
+          # All correlations for this PR share the lock: a provider may reuse
+          # an actor's pending review instead of creating a distinct object.
+          scope = [@provider.server.provider, Atoms::ServerUrl.normalize(@provider.server.url), number]
+          key = Digest::SHA256.hexdigest(scope.join("\0"))
+          File.open(File.join(Etc.systmpdir, "ace-review-session-approval-#{Process.uid}-#{key}.lock"),
+            File::CREAT | File::RDWR | File::NOFOLLOW, 0600) do |lock|
+            unless lock.stat.file? && lock.stat.uid == Process.uid && (lock.stat.mode & 0777) == 0600
+              raise ConfigError, "Unsafe approval session lock"
+            end
+            lock.flock(File::LOCK_EX)
+            pr = current!(number, expected_head)
+            actor = identity!(@request.call(:get, :actor, nil))
+            deny_author!(pr, actor)
+            rows = reviews!(number)
+            matches = rows.select { |row| row.fetch("body").include?("<!-- ace-approval:#{correlation} ") }
+            raise ProviderConflictingMatchesError, "Ambiguous approval correlation" if matches.length > 1
+            existing = matches.first
+            row!(existing) if existing
+            if existing && (existing["body"] != sent_body || existing["commit_id"] != expected_head ||
+                identity!(existing["user"]) != actor)
+              raise ProviderConflictingMatchesError, "Approval correlation is already bound to different evidence"
+            end
+            # A provider may reuse its current pending object on direct create.
+            # Only an exact known, comment-free pending review is resumable, and
+            # only when the adapter proves explicit commit preservation on reuse.
+            owned_pending = rows.select do |row|
+              row["state"] == "PENDING" && row["user"].is_a?(Hash) && row["user"]["id"] == actor.first
+            end
+            unrelated = owned_pending.any? { |row| !existing || row["id"] != existing["id"] }
+            if unrelated
+              raise ProviderConflictingMatchesError,
+                "Authenticated reviewer has an unrelated pending review; no publication performed"
+            end
+            recovering = existing && existing["state"] == "PENDING"
+            if recovering && (!@pending_reuse || existing["comments_count"] != 0 ||
+                existing["dismissed"] || existing["stale"])
+              raise ProviderUnsupportedCapabilityError,
+                "This pending review cannot be safely completed with its accepted commit/content; pending is preserved"
+            end
+            mutated = false
+            disposition = existing ? :existing : :created
+            begin
+              current!(number, expected_head)
+              if !existing || recovering
+                pending_id = existing && existing["id"]
+                mutated = true
+                # Direct approval keeps the explicit reviewed commit. Never
+                # use a later pending-submit endpoint with implicit current HEAD.
+                existing = @request.call(:post, "pulls/#{number}/reviews",
+                  {"body" => sent_body, "commit_id" => expected_head, "event" => "APPROVE"})
+                row!(existing)
+                if pending_id && existing["id"] != pending_id
+                  raise ProviderUnknownOutcomeError, "Pending review identity changed during direct approval"
+                end
+              end
+              verifying = true
+              receipt(number: number, expected_head: expected_head, review_id: existing.fetch("id"),
+                disposition: disposition, expected_body: sent_body, actor: actor)
+            rescue Error => error
+              definitive_refusal = error.is_a?(ProviderAuthenticationError) ||
+                error.is_a?(ProviderUnsupportedCapabilityError)
+              raise unless mutated && (verifying || !definitive_refusal)
+
+              raise ProviderUnknownOutcomeError,
+                "Approval outcome unknown for #{@provider.server.name}/#{number}, head #{expected_head}, " \
+                "correlation #{correlation}: #{error.class.name.split('::').last}; reconcile before repeating"
+            end
+          end
+        rescue SystemCallError
+          raise ConfigError, "Cannot acquire the private approval session lock"
+        end
+
+        def read(number:, expected_head:, review_id:)
+          validate_input!(number, expected_head)
+          unless review_id.is_a?(Integer) && review_id.positive?
+            raise ArgumentError, "Approval review ID must be a positive integer"
+          end
+          receipt(number: number, expected_head: expected_head, review_id: review_id, disposition: :existing)
+        end
+
+        private
+
+        def validate_input!(number, head)
+          unless number.is_a?(Integer) && number.positive? && head.is_a?(String) && head.match?(SHA)
+            raise ArgumentError, "Approval requires a positive PR number and full lowercase head SHA"
+          end
+        end
+
+        def current!(number, head)
+          pr = @provider.pull_request(number: number)
+          unless pr.number == number && pr.server_name == @provider.server.name &&
+              pr.head_sha == head && pr.state == :open && pr.draft == false &&
+              Atoms::ServerUrl.match?(pr.base_repository_url, @provider.server.url)
+            raise ProviderExpectedHeadConflictError,
+              "Approval requires the selected open, ready PR at the expected head"
+          end
+          pr
+        end
+
+        def identity!(user)
+          unless user.is_a?(Hash) && user["id"].is_a?(Integer) && user["id"].positive? &&
+              user["login"].is_a?(String) && !user["login"].empty?
+            raise ProviderMalformedOutputError, "Malformed authenticated review identity"
+          end
+          [user["id"], user["login"]]
+        end
+
+        def deny_author!(pr, actor)
+          unless pr.author.is_a?(String) && !pr.author.empty?
+            raise ProviderMalformedOutputError, "PR author is unverified"
+          end
+          if pr.author.casecmp?(actor.last)
+            raise ProviderAuthenticationError, "PR author cannot approve own pull request"
+          end
+        end
+
+        def row!(row)
+          unless row.is_a?(Hash) && row["id"].is_a?(Integer) && row["id"].positive? &&
+              row["body"].is_a?(String) && row["state"].is_a?(String) &&
+              row["commit_id"].is_a?(String) && row["commit_id"].match?(SHA)
+            raise ProviderMalformedOutputError, "Malformed formal review evidence"
+          end
+          identity!(row["user"])
+          row
+        end
+
+        def reviews!(number)
+          rows = @list.call("pulls/#{number}/reviews")
+          raise ProviderMalformedOutputError, "Formal reviews are not a list" unless rows.is_a?(Array)
+          rows.each do |row|
+            unless row.is_a?(Hash) && row["id"].is_a?(Integer) && row["id"].positive? &&
+                row["body"].is_a?(String) && row["state"].is_a?(String)
+              raise ProviderMalformedOutputError, "Malformed formal review list entry"
+            end
+          end
+          if rows.map { |row| row["id"] }.uniq.length != rows.length
+            raise ProviderMalformedOutputError, "Duplicate formal review IDs"
+          end
+          rows
+        end
+
+        def receipt(number:, expected_head:, review_id:, disposition:, expected_body: nil, actor: nil)
+          pr = current!(number, expected_head)
+          rows = reviews!(number)
+          row = rows.find { |entry| entry["id"] == review_id }
+          raise ProviderIdentityMismatchError, "Formal approval was not found" unless row
+          row!(row)
+          actual_actor = identity!(row["user"])
+          deny_author!(pr, actual_actor)
+          marker = row["body"].match(MARKER)
+          content = marker && row["body"][0...marker.begin(0)]
+          latest = rows.select do |entry|
+            next false unless entry["user"].is_a?(Hash) && entry["user"]["id"] == actual_actor.first
+            next false unless %w[APPROVED CHANGES_REQUESTED REQUEST_CHANGES DISMISSED].include?(entry["state"])
+
+            row!(entry)
+            unless identity!(entry["user"]) == actual_actor
+              raise ProviderIdentityMismatchError, "Inconsistent identity in relevant formal review history"
+            end
+            true
+          end.max_by { |entry| entry["id"] }
+          unless marker && !content.strip.empty? && content.bytesize <= 64 * 1024 &&
+              Digest::SHA256.hexdigest(content) == marker[2] &&
+              row["state"] == "APPROVED" && row["commit_id"] == expected_head &&
+              !row["dismissed"] && !row["stale"] && (!@official || row["official"] == true) &&
+              (!latest || latest["id"] == row["id"]) && (!expected_body || row["body"] == expected_body) &&
+              (!actor || actor == actual_actor) && row["html_url"].is_a?(String) &&
+              row["html_url"].start_with?("#{pr.url}#")
+            raise ProviderIdentityMismatchError, "Review is not the effective exact-head formal approval"
+          end
+          current!(number, expected_head)
+          ProviderApprovalReceipt.new(provider: @provider.server.provider, server_name: @provider.server.name,
+            repository_url: @provider.server.url, pr_number: number, pr_url: pr.url,
+            head_sha: expected_head, reviewer_id: actual_actor.first, reviewer: actual_actor.last,
+            review_id: row["id"], review_url: row["html_url"], state: :approved, effective: true,
+            official: @official ? row["official"] : nil,
+            correlation: marker[1], evidence_sha256: marker[2], idempotency: disposition)
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = "0.30.1"
+    VERSION = "0.31.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.30.1
+  version: 0.31.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -186,6 +186,7 @@ files:
 - lib/ace/git/providers.rb
 - lib/ace/git/providers/base.rb
 - lib/ace/git/providers/evidence.rb
+- lib/ace/git/providers/formal_approval.rb
 - lib/ace/git/resolved_server.rb
 - lib/ace/git/server_registry.rb
 - lib/ace/git/version.rb