ace-git 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '089e377ec56099fb872544bfc754f6f95f00ecaf157715ecad93e726e9c8960f'
-  data.tar.gz: 35bb8b556655c0ef1804fb2fe26039dd182115e558127254c49e17da9ce3f1ba
+  metadata.gz: 0b306e7eeb68db0b211dead9498aabdeba48ca866b13a3710a886193232d310a
+  data.tar.gz: db3448da7471947520a0aa68f70c56283f3539412456b221809ab7cd0349f976
 SHA512:
-  metadata.gz: c156b7e8b123f15f9d305d27933d68de72d640e16a803a9d7b5ce2cce12c1c7cf537bb7e6ae31e7c8ca044999869160ccf835281fdcc51e3bee76589cd43363f
-  data.tar.gz: 4eaeac69d71391c491718c68e68e1599a0a3e1991eae4a25d3e4e2a922959ef13e940c7d863eae01478a78ae9f81940a016fcac46da27ee7bbdf427f64527a03
+  metadata.gz: 0af17d14185c802e2a72f1f93c99054ea31d77ff86e3e2fd62adc2f30a99d3384dbc1f1f64de41ede47175f19ba334843ed553e775770839c41b3fc6a8232372
+  data.tar.gz: 6a5229b535fe9a4c586d1fd2e332daf90b57b0f91a899727cc677e3750aff38d55eb58f010ba1363e3956227b5f0f51879128f1bf18effac22f47236afbb53f1

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-10-02
+
+### Added
+- Normalized PR comment and review evidence, comment mutation receipts, and guarded review snapshots with exact repository and head identity.
+- Recheck PR heads around collection and before review comments or thread mutations; classify unsupported capabilities and uncertain post outcomes.
+
+
 ## [0.25.0] - 2026-09-28
 
 ### Added

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

@@ -45,6 +45,134 @@ module Ace
           provider_for(server).pull_request(number: reference.number)
         end
 
+        # Exact-head PR metadata without the diff/comment/check inventory.
+        # Delta resolution needs identity and base provenance only; pulling
+        # the full diff there would transfer it just to discard it.
+        def review_metadata_snapshot(identifier)
+          reference = parse_identifier(identifier)
+          server = resolve_server_for(reference)
+          provider = provider_for(server)
+          before = provider.pull_request(number: reference.number)
+          head = required_head!(before)
+          details = provider.pull_request_review_details(number: reference.number)
+          body_before = provider.pull_request_body(number: reference.number)
+          # Hydration is a remote read: build the metadata from the read that
+          # follows it, and re-read the body after — the task spec text lives
+          # in the body, so an edit between reads invalidates the collection.
+          after = provider.pull_request(number: reference.number)
+          body_after = provider.pull_request_body(number: reference.number)
+          if body_before != body_after
+            raise ProviderExpectedHeadConflictError,
+              "PR body changed while collecting review metadata; retry on the current head"
+          end
+          after = after.with(body: body_after) unless body_after.nil?
+          # Body hydration and identity must agree with the base provenance
+          # read before collection; a moved base invalidates the metadata.
+          latest_details = provider.pull_request_review_details(number: reference.number)
+          if after.head_sha != head || after.head_ref != before.head_ref ||
+              after.base_ref != before.base_ref || latest_details.base_sha != details.base_sha
+            raise ProviderExpectedHeadConflictError,
+              "PR head/base changed while collecting review metadata; retry on the current head"
+          end
+          ProviderReviewSnapshot.new(
+            provider: server.provider, pull_request: after,
+            base_sha: details.base_sha, files: details.files,
+            diff: nil, review_evidence: ProviderReviewEvidence.new(
+              server_name: server.name, repository_url: server.url,
+              pr_number: before.number, head_sha: head, comments: [], reviews: []
+            ),
+            checks: []
+          )
+        end
+
+        # Collect one complete review packet under an exact head/base guard.
+        # Provider failure is propagated; empty diff/comments remain valid
+        # evidence only after the full inventory and second read agree.
+        def review_snapshot(identifier, include_comments: true)
+          reference = parse_identifier(identifier)
+          server = resolve_server_for(reference)
+          provider = provider_for(server)
+          before = provider.pull_request(number: reference.number)
+          head = required_head!(before)
+          details = provider.pull_request_review_details(number: reference.number)
+          diff = provider.pull_request_diff(number: reference.number)
+          unless diff.is_a?(String)
+            raise ProviderMalformedOutputError, "PR diff is not text"
+          end
+          comments = if include_comments
+            provider.pull_request_review_evidence(number: reference.number, expected_head: head)
+          else
+            ProviderReviewEvidence.new(
+              server_name: server.name, repository_url: server.url,
+              pr_number: before.number, head_sha: head, comments: [], reviews: []
+            )
+          end
+          checks = provider.pull_request_checks(number: reference.number, head_sha: head)
+          # The CLI-parsed PR may omit the description; hydrate it from the
+          # provider's body capability when available (nil stays absence).
+          # Hydration is itself a remote read: the final identity comes from
+          # the read that follows it, so body and identity can never come
+          # from different points in time.
+          body_before = provider.pull_request_body(number: reference.number)
+          after = provider.pull_request(number: reference.number)
+          body_after = provider.pull_request_body(number: reference.number)
+          if body_before != body_after
+            raise ProviderExpectedHeadConflictError,
+              "PR body changed while collecting review evidence; retry on the current head"
+          end
+          after = after.with(body: body_after) unless body_after.nil?
+          latest_details = provider.pull_request_review_details(number: reference.number)
+          if after.head_sha != head || latest_details.base_sha != details.base_sha ||
+              after.head_ref != before.head_ref || after.base_ref != before.base_ref ||
+              after.head_repository_url != before.head_repository_url ||
+              after.base_repository_url != before.base_repository_url
+            raise ProviderExpectedHeadConflictError,
+              "PR head/base changed while collecting review evidence; retry on the current head"
+          end
+          unless details.files.is_a?(Array) && checks.is_a?(Array) &&
+              comments.head_sha == head && comments.pr_number == before.number
+            raise ProviderMalformedOutputError, "PR review evidence is incomplete or mismatched"
+          end
+          ProviderReviewSnapshot.new(
+            provider: server.provider, pull_request: after,
+            base_sha: details.base_sha, files: details.files,
+            diff: diff, review_evidence: comments, checks: checks
+          )
+        end
+
+        def post_review_comment(identifier, expected_head:, body:, correlation:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.create_pull_request_comment(
+            number: reference.number, expected_head: expected_head,
+            body: body, correlation: correlation
+          )
+        end
+
+        def update_review_comment(identifier, expected_head:, comment_id:, body:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.update_pull_request_comment(
+            number: reference.number, expected_head: expected_head,
+            comment_id: comment_id, body: body
+          )
+        end
+
+        def resolve_review_thread(identifier, expected_head:, thread_id:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.resolve_pull_request_thread(
+            number: reference.number, expected_head: expected_head,
+            thread_id: thread_id
+          )
+        end
+
+        def file_at_ref(identifier, path:, ref:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.repository_file(path: path, ref: ref)
+        end
+
         # Create (or reconcile to) a pull request for an exact base/head
         # identity. There is no identifier: the selected server's repository
         # is the base, `head_repository_url` names the source (defaults to
@@ -106,8 +234,19 @@ module Ace
           )
         end
 
+        def resolved_server_url(identifier)
+          reference = parse_identifier(identifier)
+          resolve_server_for(reference).url
+        end
         private
 
+        def required_head!(pull_request)
+          head = pull_request.head_sha
+          return head if head.to_s.match?(/\A[0-9a-f]{40}\z/)
+
+          raise ProviderMalformedOutputError, "PR evidence is missing an exact head SHA"
+        end
+
         def parse_identifier(identifier)
           reference = Atoms::PrReference.parse(identifier)
           raise ArgumentError, "Invalid PR identifier: #{identifier}" unless reference
@@ -154,7 +293,11 @@ module Ace
           end
         end
 
+        # The forge server URL for a PR identifier, resolved on demand
+      # through the shared registry (pure resolution, no mutation).
+
         def provider_for(server)
+          @resolved_server_url = server.url
           Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
         end
 

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

@@ -104,6 +104,50 @@ module Ace
           raise NotImplementedError, "Providers must implement #{self.class}#repository"
         end
 
+        # Collect normalized conversation comments, code comments and reviews
+        # for one exact PR head. A provider must reject malformed collections;
+        # an empty successful collection is represented by empty arrays.
+        def pull_request_review_evidence(number:, expected_head:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_review_evidence"
+        end
+
+        # The PR description text when the provider can supply it; nil stays
+        # an honest absence for providers whose CLI surface omits the body.
+        def pull_request_body(number:)
+          nil
+        end
+
+        # The exact base SHA and complete file inventory used to prove that a
+        # review diff has not been silently truncated.
+        def pull_request_review_details(number:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_review_details"
+        end
+
+        def pull_request_checks(number:, head_sha:)
+          raise NotImplementedError, "Providers must implement #{self.class}#pull_request_checks"
+        end
+
+        def repository_file(path:, ref:)
+          raise NotImplementedError, "Providers must implement #{self.class}#repository_file"
+        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.
+        def create_pull_request_comment(number:, expected_head:, body:, correlation:)
+          raise NotImplementedError, "Providers must implement #{self.class}#create_pull_request_comment"
+        end
+
+        def update_pull_request_comment(number:, expected_head:, comment_id:, body:)
+          raise NotImplementedError, "Providers must implement #{self.class}#update_pull_request_comment"
+        end
+
+        # Thread resolution is a separate capability. Unsupported providers
+        # must raise ProviderUnsupportedCapabilityError, never simulate success.
+        def resolve_pull_request_thread(number:, expected_head:, thread_id:)
+          raise NotImplementedError, "Providers must implement #{self.class}#resolve_pull_request_thread"
+        end
+
         # ---- PR lifecycle mutations ----
         #
         # Contract requirements (enforced by every provider implementation):

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

@@ -11,7 +11,7 @@ module Ace
     # Pull request state values: :open, :merged, :closed. Issue state values:
     # :open, :closed.
     ProviderPullRequest = Data.define(
-      :server_name, :number, :title, :state, :head_ref, :base_ref,
+      :server_name, :number, :title, :body, :state, :head_ref, :base_ref,
       :head_sha, :author, :url, :draft, :merged_at,
       :head_repository_url, :base_repository_url, :merge_commit_sha
     )
@@ -21,6 +21,33 @@ module Ace
     # Normalized check/CI evidence for one check run.
     ProviderCheck = Data.define(:server_name, :name, :state, :conclusion, :url)
 
+    # Comments keep the exact repository and PR identity supplied by the
+    # selected provider. A nil path/line denotes a conversation comment.
+    ProviderReviewComment = Data.define(
+      :server_name, :repository_url, :pr_number, :id, :author, :body,
+      :url, :path, :line, :head_sha, :resolved, :thread_id
+    )
+
+    ProviderReview = Data.define(
+      :server_name, :repository_url, :pr_number, :id, :author, :body,
+      :state, :url, :head_sha
+    )
+
+    ProviderReviewEvidence = Data.define(
+      :server_name, :repository_url, :pr_number, :head_sha, :comments, :reviews
+    )
+
+    ProviderReviewDetails = Data.define(:server_name, :repository_url, :pr_number, :base_sha, :files)
+
+    ProviderReviewSnapshot = Data.define(
+      :provider, :pull_request, :base_sha, :files, :diff, :review_evidence, :checks
+    )
+
+    ProviderReviewMutation = Data.define(
+      :server_name, :repository_url, :pr_number, :head_sha, :comment,
+      :idempotency
+    )
+
     # Normalized repository evidence.
     ProviderRepository = Data.define(:server_name, :full_name, :default_branch, :url)
 

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = "0.25.0"
+    VERSION = "0.26.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config